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 the TeamCity Web UI

Since TeamCity 9.0, you can 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 icon to edit or delete a custom chart. Note that the Add Statistic Values drop-down displays all statistic values registered on the server. 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 icon, you can also configure the Y-axis settings and save them as defaults for all users.

There is a number of limitations to editing charts from the TeamCity UI.

Reordering Custom Charts

Since TeamCity 9.0.2, you can reorder the charts for a project, since TeamCity 9.1 the same applies to build configuration 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 web UI, configure the < >/config/projects/< ProjectID >/pluginData/plugin-settings.xml following the procedure below.

Displaying Custom Chart in TeamCity Web UI

To make TeamCity display a custom chart in the web UI, you need to update the dedicated configuration file < >/config/projects/< ProjectID >/pluginData/plugin-settings.xml:

For Project-level chart: use tag <project-graphs>
For Build Configuration-level chart: use tag <buildType-graphs>

You can edit these files while the server is running, they will be automatically reloaded.

A statistics chart is added using the graph tag. See the examples below:

Custom project-level charts in plugin-settings.xml

<settings>
  <project-graphs>
   <graph title="Duration comparison" auxiliary-id="Duration comparison" hideFilters="showFailed" seriestitle="Some key" auxiliary-id="Some key" format="duration">
      <valueType key="BuildDuration" title="duration1" auxiliary-id="duration1" sourceBuildTypeId="my_first_configuration_id"/>
      <valueType key="BuildDuration" title="duration2" auxiliary-id="duration2" sourceBuildTypeId="my_second_configuration_id"/>
      <valueType key="customKey" title="Custom data" auxiliary-id="Custom data" color="#ee0055" /> <!-- Will use data from build configuration my_second_configuration_id -->
    </graph>
  </project-graphs>
</settings>

This "Duration comparison" chart will only be shown on Statistics tab of the project where the plugin-settings.xml file is located

Custom build configuration-level charts in plugin-settings.xml

<settings>
  <buildtype-graphs>
    <graph title="Passed Test Count" auxiliary-id="Passed Test Count" seriestitle="Configuration" auxiliary-id="Configuration">
      <valueType key="PassedTestCount" title="This configuration" auxiliary-id="This configuration" />
      <valueType key="PassedTestCount" title="Passed Test Count" auxiliary-id="Passed Test Count" sourceBuildTypeId="my_configuration_id"/> <!-- This is explicit reference to build configuration -->
    </graph>
    <graph title="Tests against Coverage" auxiliary-id="Tests against Coverage">
      <valueType key="PassedTestCount" title="Tests" auxiliary-id="Tests" color="#00ff00" />
      <valueType key="CodeCoverageL" title="Line coverage" auxiliary-id="Line coverage" color="#ff0000" />
    </graph>
    <graph title="Custom data" auxiliary-id="Custom data" seriestitle="Metric name" auxiliary-id="Metric name" format="size">
      <valueType key="key1" title="Metric 1" auxiliary-id="Metric 1" />
      <valueType key="key2" title="Metric 1" auxiliary-id="Metric 1" />
      <valueType key="BuildDuration" title="Duration" auxiliary-id="Duration" />
    </graph>
  </buildtype-graphs>
</settings>

These charts will be shown on Statistics tabs of the Build Types of the project where the plugin-settings.xml file is located and all it's subprojects. In order to show a chart in all Build Types register it in the Root Project.

Note that when adding custom charts, the intermediate project-graphs or buildType-graphs tag is required.

Tags Reference

<graph>: describes a single chart. It should contain one or more valueType subtags, which describe series of data shown in the chart.

Attribute	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 to include data for failed builds. averaged — hide the checkbox which allows to view averaged values. Defaults — empty (all filters are shown).
format	The format of the y-axis values. Supported formats are: `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.

<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.

Attribute	Description
key	A name of the valueType (or series). It can be predefined by TeamCity, like `BuildDuration` or `ArtifactsSize` (see below Default Statistics Values Provided by TeamCity 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>.
sourceBuildTypeId	This field allows you to explicitly specify a build configuration to use the data from for the given valueType. 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: if the `sourceBuildTypeId` is set within the `valueType`, the data is taken from this build configuration even if it belongs to a different project. 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. 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, i.e. 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, etc. 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.

<valueTypes>: allows to show several series on the chart by a pattern

Attribute	Description
pattern	Pattern for names of the Value Types (or series) to be shown on the chart. * sign is allowed to filter Value Types. Value Type can be predefined by TeamCity, like `BuildDuration` or `ArtifactsSize` (see below Default Statistics Values Provided by TeamCity 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 Value Type key. Pattern group markers could be used - eg {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 valueType. 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: if the `sourceBuildTypeId` is set within the `valueType`, the data is taken from this build configuration even if it belongs to a different project. 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. 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, i.e. this chart will work only for build configurations.

Attribute

Description

pattern

Pattern for names of the Value Types (or series) to be shown on the chart. * sign is allowed to filter Value Types. Value Type can be predefined by TeamCity, like BuildDuration or ArtifactsSize (see below Default Statistics Values Provided by TeamCity 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 Value Type key. Pattern group markers could be used - eg {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 valueType. 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:

if the sourceBuildTypeId is set within the valueType, the data is taken from this build configuration even if it belongs to a different project.
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.
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, i.e. this chart will work only for build configurations.

<graph title="Servers response time" auxiliary-id="Servers response time" seriestitle="Server" auxiliary-id="Server">
  <valueTypes pattern="Server:*" title="{1} response time" auxiliary-id="{1} response time" />
</graph>
<graph title="Build stages time" auxiliary-id="Build stages time" seriestitle="Server" auxiliary-id="Server">
  <valueTypes pattern="buildStageDuration:*" title="Stage: {1}" auxiliary-id="Stage: {1}" />
</graph>

Chart Dimensions

You can set the custom chart width/height in pixels using the width and height properties within the XML properties tag:

<graph ...>
  <properties>
    <property name="width" value="300"/>
    <property name="height" value="100"/>
  </properties>
</graph>

Chart Axis Settings

You can also customize the default axis settings for a chart via properties added withing the XML properties tag:

<graph title="Test count" auxiliary-id="Test count" seriestitle="Test group" auxiliary-id="Test group">
  <properties>
    <property name="axis.y.type" value="logarithmic"/>
    <property name="axis.y.includeZero" value="false"/>
    <property name="axis.y.max" value="10000"/>
  </properties>
  <valueType key="FailedTestCount" title="Failed" auxiliary-id="Failed" color="red"/>
  <valueType key="IgnoredTestCount" title="Ignored" auxiliary-id="Ignored" color="grey"/>
  <valueType key="PassedTestCount" title="Passed" auxiliary-id="Passed" color="green"/>
</graph>

Supported properties:

Name	Description
axis.y.type	Logarithmic for the logarithmic Y axis scale, linear for the standard scale. The default is linear.
axis.y.includeZero	Whether the zero value is included on the Y axis (true) or not (false). The default is true.
axis.y.min	An integer value to start the Y axis from.
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 the 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 Trend icon .

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 .teamcity directory)	Bytes
BuildArtifactsPublishingTime	The duration of the artifact publishing step in the build	Milliseconds
BuildCheckoutTime	The duration of the source checkout step	Milliseconds
BuildDuration	The build duration (all build stages)	Milliseconds
CodeCoverageB	Block-level code coverage	%
CodeCoverageC	Class-level code coverage	%
CodeCoverageL	Line-level code coverage	%
CodeCoverageM	Method-level code coverage	%
CodeCoverageAbsLCovered	The number of covered lines	int
CodeCoverageAbsMCovered	The number of covered methods	int
CodeCoverageAbsCCovered	The number of covered classes	int
CodeCoverageAbsLTotal	The total number of lines	int
CodeCoverageAbsMTotal	The total number of methods	int
CodeCoverageAbsCTotal	The total number of classes	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	How long the build was queued	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:

using service messages from your build,
or using the Build Script Interaction with TeamCity file.

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

Last modified: 20 April 2023