カスタムチャート

統計タブで TeamCity によって自動的に生成される統計チャートに加えて、TeamCity によって提供される統計値のセットまたはビルドスクリプトから報告された値に基づいて、独自の統計チャートを構成することもできます。後者の場合、カスタム統計データを TeamCity に報告するようにビルドスクリプトを構成する必要があります。

ビルドパラメーターページで、ビルドによって報告された統計値を表示できます。

TeamCity UI を介したカスタムチャートの管理

TeamCity Web UI を使用して、カスタムチャートを管理することができます。

カスタムチャートを追加する

プロジェクトまたはビルド構成の統計タブには、新しいチャートを作成するためのオプションがあります。現在データソースとして追加できるビルド構成は 1 つだけです。より多くの設定は手動で追加することができます。
ビルド結果ページのパラメータータブの報告された統計値リストには、新しいプロジェクトまたはビルド構成レベルチャートの統計タイプを選択するためのチェックボックスがあります。
- 選択したターゲットプロジェクトにプロジェクトレベルのチャートが追加されます。ルートプロジェクトをターゲットとして選択することはできません。
- 選択したターゲットプロジェクトとそのサブプロジェクトのすべてのビルド構成に、ビルド構成レベルのチャートが追加されます。ルートプロジェクトをターゲットとして指定すると、サーバー上で使用可能なすべてのビルド構成にチャートが追加されます。

カスタムチャートの修正

鉛筆のアイコンを使用して、カスタムグラフを編集または削除します。統計値を追加ドロップダウンメニューには、サーバーに登録されているすべての統計値が、ビルドでフィルタリングされずに表示されることに注意してください。チャートの編集時に現在のビルド構成またはプロジェクトに存在しない値を選択すると、チャートは保存されません。

歯車のアイコンを使用して、Y 軸設定を構成し、すべてのユーザーのデフォルトとして保存することもできます。

TeamCity UI からチャートを編集する場合、いくつかの制限があることに注意してください。

カスタムチャートの並べ替え

プロジェクト / ビルド構成の場合はカスタムチャートを並べ替えるには、並べ替えボタンをクリックしてチャートをドラッグアンドドロップして必要に応じて配置し、変更を適用します。

カスタムチャートを手動で管理する

TeamCity UI に表示されるカスタムチャートを手動で作成するには、<TeamCity Data Directory>/config/projects/<[ProjectID](identifier.md)>/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 UI でのカスタムチャートの表示

TeamCity が UI にカスタムチャートを表示するようにするには、<TeamCity Data Directory>/config/projects/<[ProjectID](identifier.md)>/project-config.xml 構成ファイルを更新して、新しい <extention> サブ要素を <project-extensions> 要素に追加します。

各エクステンションは、プロジェクト内で固有の id を持たなければなりません。

type 属性は

プロジェクトレベルのチャートの project-graphs
ビルド構成レベルのチャート用の buildtype-graphs

各チャートは、<parameters> 要素によって記述されます。name/value ペアでチャートに示されているデータを含む <param> サブエレメントが含まれている必要があります。series パラメーターは、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>

このチャートは、project-config.xml ファイルが配置されているプロジェクトとそのすべてのサブプロジェクトのビルド構成の統計タブに表示されます。すべてのビルド構成のチャートを表示するには、それをルートプロジェクトの project-config.xml に追加します。

パラメーターリファレンス

名前	説明
`title`	チャートの上のタイトル。
`seriesTitle`	チャートで使用されているシリーズのリストの上のタイトル（単数形）。デフォルトは `Serie` です。
`defaultFilters`	デフォルトでチェックされるコンマ区切りのオプションのリスト。以下を含めることができます。 `showFailed` — デフォルトで失敗したビルドの結果を含めます。 `averaged` — デフォルトでは、チャートに平均値を表示します。
`hideFilters`	チャートの横に表示されない、コンマ区切りのフィルター名のリスト。 `all` — すべてのフィルターを非表示にします。 `series` — シリーズフィルターを隠す (チャートに指定された特定の valueType からのデータのみを表示することはできません。) `range` — 日付範囲フィルターを非表示にします。 `showFailed` — 失敗したビルドのデータを含めることができるチェックボックスを非表示にします。 `averaged` — 平均値を表示できるチェックボックスを非表示にします。デフォルト: 空（すべてのフィルターが表示されます）。
`format`	y 軸値のフォーマットサポートされている形式は次のとおりです。 `text`、値は浮動小数点数として扱われます。 `integer`、整数値のみ。 `duration`、データはミリ秒単位でなければなりません。 `percent`、データはパーセント単位（0 から 100 まで）でなければなりません。 `percentby1`、フォーマットはパーセントとして 0 から 1 までのデータを表示します（0 から 100 まで）。 `size`、データはバイト単位である必要があります。形式が指定されていない場合は、数値形式が使用されます。

series パラメーターは JSON 形式を使用して、チャートに表示される一連のデータをリストします。各シリーズは別々の色で描かれており、フィルターを使用してシリーズを選択できます。

名前	説明
`type`	`valueType` は、チャートに表示されている一連のデータについて説明しています。各シリーズは別々の色で描かれており、フィルターを使用してシリーズを選択することができます。 `valueTypes` は `pattern` によってチャート上にいくつかの系列を表示することを可能にします ( 下記に説明)
`key`	valueType (シリーズ) の名前。`BuildDuration` や `ArtifactsSize` のように、TeamCity によって事前定義できます (事前定義された統計値の完全なリストについては以下を参照)。または、ビルドスクリプトからレポートして独自のデータを提供できます。
`title`	シリーズセレクタに表示されるシリーズ名。デフォルトは `<key>` です。いくつかのシリーズでは、パターングループマーカーを使用することができます。`{1}` はパターンの最初のキャプチャーされたグループを表し、`{0}` はパターン全体を表します。
`sourceBuildTypeId`	このフィールドでは、与えられたシリーズのデータを使用するためのビルド構成を明示的に指定できます。チャートがプロジェクトレベルで追加される場合、このフィールドはチャートで使用される最初の valueType に必須です。それ以外の場合はオプションです。ただし、TeamCity は次の規則に従ってデータを取得するためのビルド構成を選択します。 `sourceBuildTypeId` が `valueType` 内に設定されている場合、データは別のプロジェクトに属していてもこのビルド構成から取得されます。 `sourceBuildTypeId` が現在の `valueType` 内に設定されていないが、それがチャート内の現在の `valueType` 上に設定されている場合は、上で参照したビルド構成からのデータが取得されます。上記の `plugin-settings.xml` ファイルの例を参照してください。 `sourceBuildTypeId` が現在の `valueType` 内に設定されておらず、上記に設定されていない場合、チャートには現在のビルド構成のデータが表示されます。つまり、このチャートはビルド構成でのみ機能します。
`color`	グラフで使用される系列の色。標準の Web カラー形式 (「#RRGGBB」、色の名前など) を使用できます。詳細については、「HTML カラーリファレンス(英語)および HTML カラーネームリファレンス(英語)」を参照してください。指定しない場合、シリーズのタイトルに基づいて自動色が割り当てられます。
`pattern`	チャートに表示される値タイプ（またはシリーズ）の名前のパターン。アスタリスク（`*`）シンボルは、`BuildDuration` や `ArtifactsSize` などの TeamCity によって事前定義された値タイプ（またはシリーズ）をフィルタリングできます（事前定義された統計値の完全なリストについては以下を参照）。スクリプトを作成します。

チャートディメンション

param 要素の properties.width 属性と properties.height 属性を使用して、カスタムグラフの幅 / 高さをピクセル単位で設定できます: <param name="properties.width" value="300"/>

チャート軸設定

properties で始まるパラメーター名（たとえば、properties.axis.y.type）を使用して、グラフのデフォルトの軸設定をカスタマイズすることもできます。

サポートされているプロパティ:

名前	説明
`properties.axis.y.type`	標準スケールの場合は `linear` （デフォルト）。対数 Y 軸スケールの `logarithmic`
`properties.axis.y.includeZero`	ゼロ値が Y 軸に含まれるかどうか: `true` (デフォルト) `false` (ゼロは含まれていません)
`properties.axis.y.min`	Y 軸を開始する整数値。
`properties.axis.y.max`	Y 軸値の最大値として使用する整数値。

TeamCity が提供するデフォルトの統計値

以下の表は、カスタムチャートの設定に使用できる定義済みの値プロバイダを示しています。ビルドごとに報告される値は、ビルド構成設定によって異なります。

ビルドによって報告されたすべての統計値は、ビルド結果 | パラメーター | 報告された統計値タブで表示できます。それぞれの値については、チャートを見るアイコンをクリックすると統計チャートが表示されます。

キー	説明	単位
`AllTestsDuration`	このビルド中に実行されたすべてのテストの合計期間。	ミリ秒
`ArtifactsSize`	アーティファクトディレクトリ内のすべてのアーティファクトファイルサイズの合計	バイト数
`VisibleArtifactsSize`	非表示のアーティファクトを除くすべてのアーティファクトファイルサイズの合計 (`.teamcity` ディレクトリに配置されたもの)	バイト数
`buildStageDuration:artifactsPublishing`	ビルド内のアーティファクト公開ステップの期間	ミリ秒
`buildStageDuration:buildStepRunner_<N>`	各ステップの期間。バージョン 2021.2.1 以降、TeamCity はその期間の横にビルドステップ名を表示します。以前は、各ステップの ID は自動的に生成されていました。これは、名前がステップの設定で定義されていない場合、または `"title": "{0}"` が明示的に渡された場合でも当てはまります。各ステップの自動生成された ID は、ビルド構成の XML ファイルにあります。	ミリ秒
`buildStageDuration:sourcesUpdate`	ソースチェックアウトステップの期間	ミリ秒
`buildStageDuration:dependenciesResolving`	ビルドの依存関係を解決する期間	ミリ秒
`BuildDuration`	ビルド期間 (すべての構築段階)	ミリ秒
`BuildDurationNetTime`	ビルドステップの期間 (チェックアウト、アーティファクトの公開時間などを除く)	ミリ秒
`CodeCoverageB`	ブロックレベルのコードカバレッジ	%
`CodeCoverageC`	クラスレベルのコードカバレッジ	%
`CodeCoverageL`	回線レベルのコードカバレッジ	%
`CodeCoverageM`	メソッドレベルのコードカバレッジ	%
`CodeCoverageR`	分岐カバレッジ	%
`CodeCoverageS`	ステートメントのカバレッジ	%
`CodeCoverageAbsBCovered`	カバーブロック数	整数
`CodeCoverageAbsBTotal`	総ブロック数	整数
`CodeCoverageAbsCCovered`	対象クラス数	整数
`CodeCoverageAbsCTotal`	クラスの総数	整数
`CodeCoverageAbsLCovered`	カバーされた行数	整数
`CodeCoverageAbsLTotal`	総行数	整数
`CodeCoverageAbsMCovered`	対象となるメソッドの数	整数
`CodeCoverageAbsMTotal`	メソッドの総数	整数
`CodeCoverageAbsRCovered`	カバーブランチの数	整数
`CodeCoverageAbsRTotal`	ブランチの総数	整数
`CodeCoverageAbsSCovered`	対象ステートメントの数	整数
`CodeCoverageAbsSTotal`	ステートメントの総数	整数
`DuplicatorStats`	見つかったコード重複の数	整数
`TotalTestCount`	ビルド内のテストの総数	整数
`PassedTestCount`	ビルドで成功したテストの数	整数
`FailedTestCount`	ビルドで失敗したテストの数	整数
`IgnoredTestCount`	ビルドで無視されたテストの数	整数
`InspectionStatsE`	ビルド内のインスペクションエラーの数	整数
`InspectionStatsW`	ビルド内のインスペクション警告の数	整数
`SuccessRate`	ビルドが成功したかどうかの指標	0 - 失敗しました、1 - 成功
`TimeSpentInQueue`	ビルドがキューにとどまっていた期間	ミリ秒