Custom Chart

Added by Kirill Maximov, last edited by Yegor Yarko on Aug 19, 2008  (view change)
Search
Searching TeamCity 4.x Documentation
Table of Contents
This page is preliminary and subject to change.

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 configure 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 Build Configuration 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" seriesTitle="Configuration">
   <valueType key="PassedTestCount" title="This configuration" />
   <valueType key="PassedTestCount" title="Passed Test Count" buildTypeId="bt32"/> <!-- This is explicit reference to build configuration -->
 </graph>

 <graph title="Tests against Coverage">
   <valueType key="PassedTestCount" title="Tests" />
   <valueType key="CodeCoverageL" title="Line coverage" />
 </graph>

 <graph title="Custom data" seriesTitle="Metric name">
   <valueType key="key1" title="Metric 1" />
   <valueType key="key2" title="Metric 1" />
   <valueType key="BuildDuration" title="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" hideFilters="showFailed" seriesTitle="some keys">
      <valueType key="BuildDuration" title="duration2" buildTypeId="bt7"/>
      <valueType key="BuildDuration" title="duration1" buildTypeId="bt3"/> 
      <valueType key="customKey" title="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:
  1. if buildTypeId is set for the value type, data will be taken from this setting (even if corresponding build configuration belongs to another project)
  2. 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.
  3. 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.

Sources of data (valueType keys)

Pre-defined value providers

Value Description Unit
ArtifactsSize Sum of all 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
BuildTestStatus TODO — relates to MaxTimeToFixTest ???
CodeCoverage Cannot be used in custom charts  
CodeCoverageB Block-level code coverage %
CodeCoverageC Class-level code coverage %
CodeCoverageL Line-level code coverage %
CodeCoverageM Method-level code coverage %
CompositeDurationTimes Cannot be used in custom charts  
DuplicatorStats Number of found code duplicates  
FailedTestCount Number of failed tests in the build  
IgnoredTestCount Number of ignored tests in the build  
InspectionStats Cannot be used in custom charts  
InspectionStatsE Number of inspection errors in the build  
InspectionStatsW Number of inspection warnings in the build  
MaxTimeToFixTest TODO ???
MaxTimeToFixTestGraph Cannot be used in custom charts  
PassedTestCount Number of successfully passed tests in the build  
SuccessRate Indicator whether the build was successful 0 - failed, 1 - successful
TestCount Total number of tests in the build  
TestDuration Cannot be used in custom charts  
TimeSpentInQueue How much time build was in queue Milliseconds

Reporting Custom Charts Data

Custom value keys should not interfere with value keys for predefined value providers described above.

There are two ways to publish values for custom metrics — using teamcity-info.xml file or using service messages from your build.

See Also:

Labels