Custom charts: x-axis shows build numbers instead of dates, and failure rate is missing

Question

How can the x-axis of a TeamCity custom chart show dates instead of build numbers, and how can a build failure rate be charted next to the success rate?

Answer

Showing dates on the x-axis

There is no x-axis setting. The CustomChart Kotlin DSL class and the Custom Chart documentation expose only these chart properties:

properties.axis.y.type
properties.axis.y.includeZero
properties.axis.y.min
properties.axis.y.max
properties.width
properties.height

A parameter such as properties.axis.x.type is accepted as an unrecognized chart property and has no effect.

Enabling the Average filter switches the x-axis to dates. With the filter off, each point is a single build, labelled with the build number, branch and agent. With it on, points are grouped into time periods and labelled with the date.

Set the filter on by default in the Kotlin DSL:

projectCustomChart {
    id = "buildDurationChart"
    title = "Build Performance Breakdown"
    seriesTitle = "Duration Metrics"
    format = CustomChart.Format.DURATION
    defaultFilters = listOf(CustomChart.DefaultFilters.AVERAGED)
    series = listOf(
        Serie(
            title = "Total Build Duration",
            key = CustomChart.SeriesKey.BUILD_DURATION,
            sourceBuildTypeId = "MyProject_Build"
        )
    )
}

The filter averages the data into buckets, so individual builds stop being distinguishable. Where dated labels and per-build values are both needed, no combination of settings provides them. Option to display dates on X axis of statistics charts instead of build numbers tracks a dedicated x-axis option.

The Average checkbox also appears next to the chart, so the effect can be checked before any configuration changes. Filter defaults are a different matter: they can be set only through the DSL or project-config.xml, because the UI chart editor cannot configure them.

Charting a failure rate

There is no failure-rate statistic value. BuildFailureRate is not a recognized key. A series that names it stays empty, because a statistic value reaches a chart only when it holds data. The built-in keys are listed under "Default Statistics Values Provided by TeamCity" in the Custom Chart documentation.

The closest built-in value is SuccessRate, which is 1 for a successful build and 0 for a failed one. A failure rate is its inverse, and no built-in series provides that. Two options remain:

1. Report a custom metric from the build with a service message, then chart that key. The "Custom Build Metrics" section of the Custom Chart documentation covers this, and notes that custom keys must not collide with built-in ones.
2. Export build data through the TeamCity REST API and chart it in an external tool.

Configuring a success-rate chart

defaultFilters must include SHOW_FAILED. Without it, failed builds are excluded from the data and every plotted value is 1, which reads as a permanent 100% success rate. Adding AVERAGED turns the series into a rate over a period rather than a step chart of 0 and 1. The built-in Success Rate chart enables both filters by default.

The format needs to be the 0-to-1 percentage variant, because SuccessRate produces values between 0 and 1. CustomChart.Format.PERCENT is the wrong one: it treats the value as already being a percentage, so a success rate of two builds out of three is drawn at 0.67 on an axis running to 100, flattening the series against the bottom with a label of 0.7%.

CustomChart.Format.PERCENT_BY_1 is the right variant, but it does not currently work from the Kotlin DSL. The enum emits the format name in lower case, and the chart expects it camel-cased, so the format is not recognized and the axis falls back to plain numbers. This is tracked as Kotlin DSL: CustomChart.Format.PERCENT_BY_1 emits percentby1 and the format is ignored. Set the parameter directly instead, and do not also assign the typed format property, because both write the same key:

param("format", "percentBy1")

yAxisMin and yAxisMax are worth setting as well, and with this format their unit is the percentage rather than the underlying 0-to-1 value. yAxisMin = 0 with yAxisMax = 100 gives a full-scale chart.

Avoid yAxisType = LOGARITHMIC on this chart. A period in which every build failed has the value 0, and a logarithmic scale has no zero, so such periods disappear from the chart.

projectCustomChart {
    id = "buildSuccessRateChart"
    title = "Build Success Rate Breakdown"
    seriesTitle = "Success Rate Metrics"
    param("format", "percentBy1")
    defaultFilters = listOf(
        CustomChart.DefaultFilters.AVERAGED,
        CustomChart.DefaultFilters.SHOW_FAILED
    )
    yAxisMin = 0
    yAxisMax = 100
    series = listOf(
        Serie(
            title = "Success Rate",
            key = CustomChart.SeriesKey.SUCCESS_RATE,
            sourceBuildTypeId = "MyProject_Build"
        )
    )
}

Builds that failed to start are a separate case. They stay out of success-rate statistics whatever the Show failed filter is set to. Ability to include failed to start builds into Success rate statistics chart and Need statistics to show failed to start builds track that gap.