TeamCity Cloud 2023.09 Help

Custom Chart

In addition to statistic charts generated automatically by TeamCity on the Statistics tab, it is possible to configure your own statistical charts based on the set of statistic values provided by TeamCity or values reported from a build script. In the latter case you will need to configure your build script to report custom statistical data to TeamCity.

You can view statistic values reported by the build on the Build Parameters page.

Managing Custom Charts via TeamCity UI

It is possible to manage custom charts using the TeamCity web UI.

Adding Custom Charts

  • The Statistics tab for a project or build configuration provides an option to create a new chart. Note that only one build configuration can be currently added as the data source. More configurations can be added manually.

  • On the Parameters tab of the build results page, the list of Reported statistic values provides checkboxes to select the statistics type for a new project- or build-configuration-level chart.

    • A project-level chart will be added to the selected target project. The root project cannot be selected as the target.

    • A build-configuration-level chart will be added to all build configurations of the selected target project and its subprojects. Specifying the root project as the target will add the chart to all build configurations available on the server.

Modifying Custom Charts

Use the pencil pencil.JPG icon to edit or delete a custom chart. Note that the Add Statistic Values drop-down menu displays all statistic values registered on the server without filtering them by build. If you select a value non-existent in the current build configuration or project when editing a chart, the chart will not be saved.

Using the cog cog.JPG icon, you can also configure the Y-axis settings and save them as defaults for all users.

Note that there is a number of limitations to editing charts from the TeamCity UI.

Reordering Custom Charts

To reorder custom charts for a project/build configuration, click the Reorder button and drag-and-drop the charts to arrange them as required and apply your changes.

Managing Custom Charts Manually

To manually create custom charts to be displayed in the TeamCity UI, configure the <TeamCity Data Directory>/config/projects/<ProjectID>/project-config.xml file. The file has the <project-extensions> element which contains all project features, including custom charts. For each chart an <extention> element is added.

Charts can also be configured via Kotlin DSL. Example configuration:

features { projectCustomChart { id = "SampleChart" title = "Success Rate" seriesTitle = "Serie" format = CustomChart.Format.PERCENT series = listOf( Serie(title = "Success Rate", key = SeriesKey.SUCCESS_RATE, sourceBuildTypeId = "testBuild") ) } }

See the reference on available parameters below.

Displaying Custom Chart in TeamCity UI

To make TeamCity display a custom chart in the UI, update the <TeamCity Data Directory>/config/projects/<ProjectID>/project-config.xml configuration file adding a new <extention> sub-element to the <project-extensions> element.

Each extension must have a unique id in the project.

The type attribute is set to

  • project-graphs for project-level chart

  • buildtype-graphs for build configuration-level chart

Each chart is described by the <parameters> element. It must contain the <param> sub-elements with data shown in the chart in name/value pairs; the series parameter uses the JSON format to list series of data shown on the chart.

See the example below:

Custom build configuration-level chart in project-config.xml

<project-extensions>  <extension id="customChart1" type="buildtype-graphs">    <parameters>      <param name="title" value="Custom chart"/>      <param name="hideFilters" value="showFailed"/>      <param name="seriesTitle" value="Some key"/>      <param name="format" value="duration"/>      <param name="series"><![CDATA[[ {  "type": "valueType",  "key": "BuildDuration",  "title": "duration1",  "sourceBuildTypeId": "my_first_configuration_id" }, {  "type": "valueType",  "key": "customKey",  "title": "Custom data",  "color": "#ee0055 " }, {  "type": "valueTypes",  "pattern": "buildStageDuration:*",  "title": "Stage: {1}" } ]]]>      </param>      <param name="properties.width" value="300"/>      <param name="properties.height" value="300"/>      <param name="properties.axis.y.type" value="logarithmic"/>      <param name="properties.axis.y.includeZero" value="false"/>      <param name="properties.axis.y.max" value="10000"/>    </parameters>  </extension>  <extension id="secondChart" type="buildtype-graphs">    <parameters>      <param name="title" value="empty"/>    </parameters>  </extension> </project-extensions>

This chart will be shown on the Statistics tabs of the build configurations of the project where the project-config.xml file is located and all its subprojects. To display a chart for all build configurations, add it to the project-config.xml of the Root project.

Parameters Reference

Name

Description

title

The title above the chart.

seriesTitle

The title above the list of series used on the chart (in the singular form). The default is Serie.

defaultFilters

The list of comma-separated options to be checked by default. Can include the following:

  • showFailed — include results from failed builds by default.

  • averaged — by default, show averaged values on the chart.

hideFilters

The list of comma-separated filter names that will not be shown next to the chart:

  • all — hide all filters.

  • series — hide series filter (you won't be able to show only data from specific valueType specified for the chart.)

  • range — hide the date range filter.

  • showFailed — hide the checkbox which allows including data for failed builds.

  • averaged — hide the checkbox which allows viewing averaged values.

Default: empty (all filters are shown).

format

The format of the y-axis values. Supported formats are:

  • text, value is treated as float;

  • integer, only integer values;

  • duration, data should be in milliseconds;

  • percent, data should be in percents (from 0 to 100);

  • percentby1, the format will show data between 0 and 1 as percents (from 0 to 100);

  • size, data should be in bytes.

If no format is specified, the numeric format is used.

The series parameter uses JSON format to list series of data shown on the chart. Each series is drawn in a separate color and you can choose one or another series using a filter.

Name

Description

type

  • valueType describes a series of data shown on the chart. Each series is drawn with a separate color and you may choose one or another series using a filter.

  • valueTypes allows displaying several series on the chart by a pattern (described below)

key

The name of the valueType (series). It can be predefined by TeamCity, like BuildDuration or ArtifactsSize (see below for the complete list of predefined statistic values), or you can provide your own data by reporting it from the build script.

title

The series name shown in the series selector. Defaults to <key>. For several series, pattern group markers can be used: {1} stands for the first captured group in the pattern, {0} stands for the whole pattern.

sourceBuildTypeId

This field allows you to explicitly specify a build configuration to use the data from for the given series. This field is mandatory for the first valueType used in a chart if the chart is added at the project level. In other cases it is optional. However, note that TeamCity chooses the build configuration to take the data from according to the following rules:

  1. if the sourceBuildTypeId is set within the valueType, the data is taken from this build configuration even if it belongs to a different project.

  2. if the sourceBuildTypeId is not set within current the valueType, but it is set in the valueType above the current one within the chart, the data from the build configuration referenced above will be taken. See example for the plugin-settings.xml file above.

  3. if the sourceBuildTypeId is not set within current the valueType and is not set above, the chart will show data for the current build configuration, that is this chart will work only for build configurations.

color

The color of a series to be used in the chart. Standard web color formats can be used - "#RRGGBB", color names, and so on. For more information see HTML Colors reference and HTML Color Names reference. If not specified, an automatic color will be assigned based on the series title.

pattern

Pattern for names of the Value Types (or series) to be shown on the chart. The asterisk (*) symbol is allowed to filter Value Types (or series) either predefined by TeamCity, like BuildDuration or ArtifactsSize (see below for the complete list of predefined statistic values), or your own data can be provided by reporting it from the build script.

Chart Dimensions

You can set the custom chart width/height in pixels using the properties.width and properties.height attributes for the param elements: <param name="properties.width" value="300"/>.

Chart Axis Settings

You can also customize the default axis settings for a chart via parameter names starting with properties: for example, properties.axis.y.type.

Supported properties:

Name

Description

properties.axis.y.type

  • linear (default) for the standard scale.

  • logarithmic for the logarithmic Y axis scale

properties.axis.y.includeZero

Whether the zero value is included on the Y axis:

  • true (default)

  • false (zero is not included)

properties.axis.y.min

An integer value to start the Y axis from.

properties.axis.y.max

An integer value to use as the maximum for the Y axis value .

Default Statistics Values Provided by TeamCity

The table below lists the predefined value providers that can be used to configure a custom chart. The values reported for each build differ depending on your build configuration settings.

You can view all statistic values reported by the build on the Build Results | Parameters | Reported statistic values tab. For each of the values, a statistics chart is available on clicking the View Chart icon ViewTrend.PNG.

Key

Description

Unit

ArtifactsSize

The sum of all artifact file sizes in the artifact directory

Bytes

VisibleArtifactsSize

The sum of all artifact file sizes excluding hidden artifacts (those placed under the .teamcity directory)

Bytes

buildStageDuration:artifactsPublishing

The duration of the artifact publishing step in the build

Milliseconds

buildStageDuration:buildStepRunner_<N>

The duration of each step.

Since version 2021.2.1, TeamCity displays the build step name next to its duration. Previously, each step's ID was generated automatically. This is still the case when the name is not defined in the step's settings or if "title": "{0}" is passed explicitly. The autogenerated ID of each step can be found in the XML file of the build configuration.

Milliseconds

buildStageDuration:sourcesUpdate

The duration of the source checkout step

Milliseconds

buildStageDuration:dependenciesResolving

The duration of resolving dependencies of the build

Milliseconds

BuildDuration

The build duration (all build stages)

Milliseconds

BuildDurationNetTime

The build steps' duration (excluding the checkout, artifact publishing time, and so on)

Milliseconds

CodeCoverageB

Block-level code coverage

%

CodeCoverageC

Class-level code coverage

%

CodeCoverageL

Line-level code coverage

%

CodeCoverageM

Method-level code coverage

%

CodeCoverageR

Branch coverage

%

CodeCoverageS

Statement coverage

%

CodeCoverageAbsBCovered

The number of covered blocks

int

CodeCoverageAbsBTotal

The total number of blocks

int

CodeCoverageAbsCCovered

The number of covered classes

int

CodeCoverageAbsCTotal

The total number of classes

int

CodeCoverageAbsLCovered

The number of covered lines

int

CodeCoverageAbsLTotal

The total number of lines

int

CodeCoverageAbsMCovered

The number of covered methods

int

CodeCoverageAbsMTotal

The total number of methods

int

CodeCoverageAbsRCovered

The number of covered branches

int

CodeCoverageAbsRTotal

The total number of branches

int

CodeCoverageAbsSCovered

The number of covered statements

int

CodeCoverageAbsSTotal

The total number of statements

int

DuplicatorStats

The number of code duplicates found

int

TotalTestCount

The total number of tests in the build

int

PassedTestCount

The number of successfully passed tests in the build

int

FailedTestCount

The number of failed tests in the build

int

IgnoredTestCount

The number of ignored tests in the build

int

InspectionStatsE

The number of inspection errors in the build

int

InspectionStatsW

The number of inspection warnings in the build

int

SuccessRate

An indicator whether the build was successful

0 - failed, 1 - successful

TimeSpentInQueue

For how long the build was staying in the queue

Milliseconds

Custom Build Metrics

If the predefined build metrics do not cover your needs, you can report custom metrics to TeamCity from your build script and use them to create a custom chart. There are two ways to report custom metrics to TeamCity:

Note that custom value keys should be unique and should not interfere with value keys predefined by TeamCity.

Last modified: 07 September 2023