自定义图表

除了由 TeamCity 在统计标签页自动生成的统计图表外，还可以根据 TeamCity 提供的一组统计值或构建脚本报告的值配置您自己的统计图表。在后一种情况下，您需要配置您的构建脚本以向 TeamCity 报告自定义统计数据。

您可以在 构建参数 页面上查看构建报告的统计值。

通过 TeamCity 用户界面管理自定义图表

您可以使用 TeamCity 网页用户界面管理自定义图表。

添加自定义图表

项目或构建配置的 Statistics 标签页提供了创建新图表的选项。请注意，目前只能添加一个构建配置作为数据源。可以手动添加更多配置。
在构建结果页面的参数标签页上，报告的统计值 列表提供了复选框，可以选择新的项目或构建配置级别图表的统计类型。
- 一个项目级图表将被添加到所选的目标项目中。 root project 不能被选为目标。
- 将为所选目标项目及其子项目的所有构建配置添加构建配置级别的图表。指定 root project 为目标将会把图表添加到服务器上可用的所有构建配置中。

修改自定义图表

使用铅笔图标来编辑或删除自定义图表。请注意，添加统计值 下拉菜单会显示服务器上注册的所有统计值，而不会按构建进行过滤。如果您在编辑图表时选择了当前构建配置或项目中不存在的值，那么图表将不会被保存。

使用齿轮图标，您也可以配置 Y轴设置，并将它们保存为所有用户的默认设置。

请注意，从 TeamCity UI 编辑图表存在一些限制。

重新排序自定义图表

要对项目/构建配置的自定义图表进行重新排序，请点击 重新排序 按钮并拖放图表进行安排，然后应用您的更改。

手动管理自定义图表

要在 TeamCity UI 中手动创建自定义图表，请配置 <TeamCity 数据目录>/config/projects/<ProjectID>/project-config.xml 文件。该文件包含了 <project-extensions> 元素，它涵盖了所有项目特性，包括自定义图表。对于每个图表，都会添加一个 <extention> 元素。

图表也可通过 Kotlin DSL 进行配置。示例配置：

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")
    )
  }
}

请参阅下方下面的可用参数说明。

在 TeamCity 用户界面中显示自定义图表

为了让 TeamCity 在 UI 中显示自定义图表，更新 <TeamCity 数据目录>/config/projects/<ProjectID>/project-config.xml 配置文件，向 <project-extensions> 元素中添加新的 <extention> 子元素。

每个扩展在项目中必须有一个唯一的 iD。

类型 属性被设置为

project-graphs 用于项目级图表
用于构建配置级别的图表

每个图表都由 <parameters> 元素描述。它必须包含 <param> 子元素，数据显示在 名称/值 对的图表中； 系列 参数使用 JSON 格式列出图表上显示的数据系列。

请参见下面的示例：

自定义构建配置级别的图表在 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>

这个图表将会在项目中 Statistics 标签页的构建配置以及 project-config.xml 文件所在位置和它的所有子项目中展示。要显示所有构建配置的图表，请将其添加到 Root project 的 project-config.xml 中。

参数参考

名称	描述
`标题`	图表上方的标题。
`seriesTitle`	在图表上使用的系列列表上方的标题（用单数形式）。默认设置为 `系列`。
`defaultFilters`	默认情况下要检查的逗号分隔选项的列表。可以包含以下内容： `showFailed` — 默认包括失败构建的结果。 `平均` — 默认情况下，图表上显示平均值。
`hideFilters`	将不会在图表旁边显示的逗号分隔的过滤器名称列表： `全部` — 隐藏所有筛选器。 `系列` — 隐藏系列过滤器（您将无法仅显示图表中指定的特定 valueType 的数据。） `range` — 隐藏日期范围过滤器。 `showFailed` — 隐藏允许包含失败构建数据的复选框。 `平均` — 隐藏允许查看平均值的复选框。默认：空（显示所有过滤器）。
`进行表示`	y 轴值的格式。支持的格式包括： `文本` ，值被视为浮点数； `整数` ，只允许整数值； `持续时间` ，数据应以毫秒为单位； `百分比` ，数据应以百分比的形式表示（从 0 到 100）； `percentby1` ，该格式将显示0至1之间的数据为百分比（从0至100）； `大小` ，数据应以字节形式存在。如果没有指定格式，将使用数字格式。

系列 参数使用 JSON 格式来列出图表上显示的一系列数据。每个系列都以不同的颜色绘制，您可以使用过滤器选择一个或另一个系列。

名称	描述
`类型`	`valueType` 描述了图表上展示的一系列数据。每个系列都会用不同的颜色进行绘制，您可以使用过滤器选择一个或另一个系列。 `值类型` 允许通过 `模式` 在图表上显示多个系列（如下文所述）
`密钥`	valueType （系列）的名称。它可以被 TeamCity 预定义，例如 `构建持续时间` 或 `ArtifactsSize` （有关预定义统计值的完整列表，请参阅下方的 below），或者您可以通过从构建脚本中报告来提供您自己的数据。
`标题`	在系列选择器中显示的系列名称。默认为 `<key>`。对于若干系列，可以使用模式组标记： `{1}` 代表模式中捕获的第一组， `{0}` 代表整个模式。
`sourceBuildTypeId`	此字段允许您明确指定一个构建配置，以便为给定系列使用其数据。如果在项目级别添加图表，则此字段对于图表中使用的第一个 valueType 是必填的。在其他情况下，这是可选的。然而，请注意，TeamCity 根据以下规则选择从哪个构建配置中获取数据：如果 `sourceBuildTypeId` 在 `valueType` 中设置，即使它属于不同的项目，数据也会从这个构建配置中获取。如果 `sourceBuildTypeId` 没有在当前的 `valueType` 中设定，但在位于当前项上方的 `valueType` 中设定了，那么将会使用来自上述构建配置的数据。请参阅上面的 `plugin-settings.xml` 文件示例。如果 `sourceBuildTypeId` 没有在当前的 `valueType` 中设置，也没有在上方设置，图表将显示当前构建配置的数据，也就是说，该图表仅适用于构建配置。
`颜色`	在图表中要使用的系列的颜色。标准的网络颜色格式可以使用 - "#RRGGBB" ，颜色名称等等。有关更多信息，请参阅 HTML 颜色参考和 HTML 颜色名称参考。如果没有指定，将根据系列标题自动分配颜色。
`模式`	要在图表上显示的值类型（或系列）名称的模式。星号（ `*` ）符号可用于筛选由 TeamCity 预定义的值类型（或系列），如 `构建持续时间` 或 `ArtifactsSize` （请参阅以下预定义统计值的完整列表），或者您可以通过从构建脚本中报告来提供您自己的数据。

图表尺寸

您可以使用 properties.width 和 properties.height 属性在 param 元素中设置自定义图表的像素宽度/高度： <param name="properties.width" value="300"/>。

图表轴设置

您也可以通过以 属性 开头的参数名称来自定义图表的默认轴设置，例如 properties.axis.y.type。

支持的属性：

名称	描述
`properties.axis.y.type`	`线性` （默认）用于标准刻度。 `对数的` 用于对数 Y 轴比例尺
`properties.axis.y.includeZero`	Y轴是否包含零值： `true` （默认） `false` （零不包括在内）
`properties.axis.y.min`	一个整数值，作为 Y 轴的起始点。
`properties.axis.y.max`	用作 Y 轴值最大值的整数值。

TeamCity 提供的默认统计值

下表列出了可用于配置自定义图表的预定义值提供者。每个构建报告的值会根据您的构建配置设置有所不同。

您可以在 构建结果 | 参数 | 报告的统计值 标签页上查看构建报告的所有统计值。对于每一个值，点击 查看图表 图标后都可查看相应的统计图表。

密钥	描述	单元
`ArtifactsSize`	所有 artifact 文件在 artifact 目录中的总大小	字节
`VisibleArtifactsSize`	所有 artifact 文件的总大小，不包括隐藏的 artifacts（放置在 `.teamcity` 目录下的）。	字节
`buildStageDuration:artifactsPublishing`	构建中的构件发布步骤的持续时间	毫秒
`buildStageDuration:buildStepRunner_<N>`	每个步骤的持续时间。自2021.2.1版本开始，TeamCity 在显示构建步骤的持续时间旁边会显示构建步骤的名称。之前，每个步骤的 ID 都是自动生成的。当名称未在步骤的设置中定义，或者如果明确传递了 `"标题"：" {0}"` 时，仍然如此。每个步骤的自动生成 ID 可在构建配置的 XML 文件中找到。	毫秒
`buildStageDuration:sourcesUpdate`	源代码检出步骤的持续时间	毫秒
`buildStageDuration:dependenciesResolving`	解析构建依赖项的持续时间	毫秒
`构建持续时间`	构建持续时间（所有构建阶段）	毫秒
`BuildDurationNetTime`	构建步骤的持续时间（不包括检出、发布工件的时间等）	毫秒
`CodeCoverageB`	块级代码覆盖率	%
`CodeCoverageC`	类级别的代码覆盖率	%
`CodeCoverageL`	行级代码覆盖率	%
`CodeCoverageM`	方法级代码覆盖率	%
`CodeCoverageR`	分支覆盖率	%
`CodeCoverageS`	语句覆盖率	%
`CodeCoverageAbsBCovered`	覆盖的块数	int
`CodeCoverageAbsBTotal`	总块数	int
`CodeCoverageAbsCCovered`	被覆盖的类的数量	int
`CodeCoverageAbsCTotal`	类的总数	int
`CodeCoverageAbsLCovered`	被覆盖的行数	int
`CodeCoverageAbsLTotal`	总行数	int
`CodeCoverageAbsMCovered`	被覆盖方法的数量	int
`CodeCoverageAbsMTotal`	方法的总数	int
`CodeCoverageAbsRCovered`	覆盖分支的数量	int
`CodeCoverageAbsRTotal`	分支总数	int
`CodeCoverageAbsSCovered`	覆盖语句的数量	int
`CodeCoverageAbsSTotal`	语句的总数	int
`DuplicatorStats`	找到的代码重复数量	int
`TotalTestCount`	构建中的测试总数	int
`通过的测试数量`	构建中成功通过的测试数量	int
`失败的测试数`	构建中失败测试的数量	int
`IgnoredTestCount`	构建中被忽略的测试数量	int
`InspectionStatsE`	构建中的检查错误数量	int
`InspectionStatsW`	构建中的检查警告数量	int
`SuccessRate`	一个指示器，表示构建是否成功	0 - 失败，1 - 成功
`在队列中所花费的时间`	构建在队列中停留了多长时间	毫秒

定制构建度量

如果预定义的构建度量无法满足您的需求，您可以从您的构建脚本向 TeamCity 报告自定义度量，并用它们来创建自定义图表。有两种方法可以向 TeamCity 报告自定义度量：

使用来自您的构建的 service messages，
或者（已过时的方法）使用 teamcity-info.xml 文件。

请注意，自定义值键应该是唯一的，且不应与 TeamCity 预定义的值键冲突。

最后修改日期： 16日 7月 2024年