Custom Chart

Overview

In TeamCity, it is possible to configure a build script to report statistical build data (build metrics) and then display the data on charts.

To display a custom chart you will need to Reporting-Custom-Charts-Data your build script to report the data and configure TeamCity to show the corresponding charts.

Configuring Charts Presentation

TeamCity allows to display custom charts either on the Statistics page or on the Project Statistics Page, depending on the settings.

The settings for custom charts are stored in the XML files. In the chart configuration, you can use either pre-defined metrics provided by TeamCity, or the values reported from the build script.

Build-Configuration Level Charts

The chart is shown on the Statistics tab of the Build Configuration. The chart is displayed for those Build Configurations that has appropriate data reported by the builds.

The settings are configured in the < TeamCity data dir >/config/main-config.xml file by "graph" tags. You can edit the file while server is running, it will be automatically reloaded.

<server ...>

 <!-- Some other stuff -->

 <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" buildTypeId="bt32"/> <!-- 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" />
   <valueType key="CodeCoverageL" title="Line coverage" auxiliary-id="Line coverage" />
 </graph>

 <graph title="Custom data" auxiliary-id="Custom data" seriestitle="Metric name" auxiliary-id="Metric name">
   <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>

</server>

Project-Level Charts

The chart is shown on the Statistics tab for the individual Project.

The settings are configured in the < TeamCity data dir >/config/<Project Name>/plugin-settings.xml file by "graph" tags. You can edit the file while server is running, it will be automatically reloaded.

Almost the same as for main-config.xml, but there is an intermediate custom-graphs tag:

<settings>

  <custom-graphs>

   <graph title="Duration comparison" auxiliary-id="Duration comparison" hideFilters="showFailed" seriestitle="some keys" auxiliary-id="some keys">
      <valueType key="BuildDuration" title="duration2" auxiliary-id="duration2" buildTypeId="bt7"/>
      <valueType key="BuildDuration" title="duration1" auxiliary-id="duration1" buildTypeId="bt3"/>
      <valueType key="customKey" title="Custom data" auxiliary-id="Custom data" /> <!-- Will use data from build configuration bt3 -->
    </graph>

  </custom-graphs>

</settings>

Tags description

<graph>

This tag describes a single chart. It may contain one or more valueType subtags, which describe series of data shown on the chart.

Attribute	Description
title	Title above the chart
seriesTitle	Title above list of series used on the chart (in singular form). Defaults to "Serie"
defaultFilters	List of comma-separated options, which should be checked by default. May include the following options: showFailed — include results from failed builds by default averaged — by default, show averaged values on the chart
hideFilters	List of comma-separated filter names, which should not be shown near the chart: all — hide all filters series — hide series filter (you won't be able to show only data from specific value type specified for the chart range — hide date range filter showFailed — hide checkbox which allows to include data for failed builds averaged — hide checkbox which allows to view averaged values Defaults — empty (all filters are shown)

<valueType>

This tag 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. The attributes of the tag are:

Attribute	Description
key	A name of the value type (or series). It may be predefined by TeamCity, like "BuildDuration" or "ArtifactsSize", or you can provide your own data (see below)
title	Series name, shown in the series selector. Defaults to <key>.
buildTypeId	This field is mandatory for the first value type used in a chart on Project Statistics page, and can be omitted in other cases. It allows to specify build configuration, whose data will be shown for given value type. The build configuration for the data is chosen by the following rules: if `buildTypeId` is set for the value type, data will be taken from this setting (even if corresponding build configuration belongs to another project) if `buildTypeId` is not set for the current value type, but it is set for a value type above current one within the chart, the data from the build configuration referenced above will be taken. See example for `plugin-settings.xml` file above. if `buildTypeId` is not set for the current value type and is not set above, the chart will show data for the current build configuration, i.e. this chart will work only for Statistics tab of the build configuration. Such charts can be configured only in `main-config.xml`.

Attribute

Description

key

A name of the value type (or series). It may be predefined by TeamCity, like "BuildDuration" or "ArtifactsSize", or you can provide your own data (see below)

title

Series name, shown in the series selector. Defaults to <key>.

buildTypeId

This field is mandatory for the first value type used in a chart on Project Statistics page, and can be omitted in other cases. It allows to specify build configuration, whose data will be shown for given value type. The build configuration for the data is chosen by the following rules:

if buildTypeId is set for the value type, data will be taken from this setting (even if corresponding build configuration belongs to another project)
if buildTypeId is not set for the current value type, but it is set for a value type above current one within the chart, the data from the build configuration referenced above will be taken. See example for plugin-settings.xml file above.
if buildTypeId is not set for the current value type and is not set above, the chart will show data for the current build configuration, i.e. this chart will work only for Statistics tab of the build configuration. Such charts can be configured only in main-config.xml.

Data Sources (valueType keys)

Pre-defined Value Providers

Value	Description	Unit
ArtifactsSize	Sum of all Build Artifact file sizes in artifact directory.	Bytes
BuildArtifactsPublishingTime	Duration of the artifact publishing step in the build.	Milliseconds
BuildCheckoutTime	Duration of the source checkout step.	Milliseconds
BuildDuration	Build duration, excluding checkout or artifact publishing time.	Milliseconds
CodeCoverageB	Block-level code coverage	%
CodeCoverageC	Class-level code coverage	%
CodeCoverageL	Line-level code coverage	%
CodeCoverageM	Method-level code coverage	%
DuplicatorStats	Number of found code duplicates
FailedTestCount	Number of failed tests in the build
IgnoredTestCount	Number of ignored tests in the build
InspectionStatsE	Number of inspection errors in the build
InspectionStatsW	Number of inspection warnings in the build
PassedTestCount	Number of successfully passed tests in the build
SuccessRate	Indicator whether the build was successful	0 - failed, 1 - successful
TestCount	Number of failed tests in the build
TimeSpentInQueue	How much time build was in queue	Milliseconds

Reporting Custom Charts Data

There are two ways to publish values for custom metrics — Build Script Interaction with TeamCity file or using Build Script Interaction with TeamCity from your build.

Last modified: 20 April 2023