# Grafana統合 {#grafana}

Tuistのデータソースを使用すると、ビルド時間、失敗数、キャッシュによる節約時間など、ビルド、テスト、キャッシュのメトリクスをGrafanaで利用できます。チームが重視するプロジェクトやメトリクスを中心にダッシュボードを構築したり、社内既存のダッシュボードでTuistのメトリクスを他のデータソースと組み合わせたりできます。Grafanaのアラートルールと通知チャネルを活用し、ビルドが遅くなったり失敗が増加した際にチームに通知しましょう。

## 利用可能なメトリクス {#metric-definitions}

テーブルには、読みやすいラベルとそのクエリ識別子が記載されています。ビルド健全性のクエリでは`metric`フィールドの識別子を使用し、ビルドおよびテスト時間のクエリでは`series`フィールドで`average`、`p50`、`p90`、または`p99`を選択します。

### ビルド数と信頼性

| メトリクス | 識別子 | 測定内容 |
| --- | --- | --- |
| ビルド数 | `builds` | 記録されたビルドの数。 |
| 成功したビルド | `successful_builds` | 正常に完了したビルド。 |
| 失敗したビルド | `failed_builds` | 失敗したビルド。 |
| キャンセルされたビルド | `cancelled_builds` | キャンセルとして記録されたビルド。[ビルドシステムの差異](#build-systems)を参照してください。 |
| ビルド成功率 | `success_rate` | 成功 ÷ (成功 + 失敗) の割合（パーセント）。 |
| 失敗または低速なビルド | `builds_needing_attention` | 失敗したビルドまたは低速なビルドを、ビルドごとに1回カウント。 |

### ビルドおよびテスト時間

| メトリクス | 識別子 | 測定内容 |
| --- | --- | --- |
| 平均時間 | `average` | 選択した実行の平均時間。 |
| 中央値時間 | `p50` | 実行時間の50パーセンタイル。 |
| 90パーセンタイル時間 | `p90` | 実行の90%がこの時間以下になる値。 |
| 99パーセンタイル時間 | `p99` | 実行の99%がこの時間以下になる値。 |
| 低速ビルドのしきい値 | `slow_build_threshold` | 90パーセンタイル時間、またはミリ秒単位の固定制限値。 |

テスト時間のメトリクスは、Tuistに記録されたテスト実行を使用します。低速ビルドのしきい値はビルドにのみ適用され、ビルド時間がそのしきい値を超えると低速と判定されます。キャンセルされたビルドは別々にカウントされ、ビルド成功率からは除外されます。

### キャッシュによる節約

| メトリクス | 識別子 | 測定内容 |
| --- | --- | --- |
| 累積タスク時間の節約（Gradle） | `cache_work_avoided` | キャッシュヒットによって回避された推定タスク実行時間の合計。 |
| 累積タスク時間を報告するビルド | `cache_work_avoided_samples` | 完全な見積もりを持つビルド。 |
| 報告されたキャッシュによる時間節約 | `cache_time_saved` | 報告された経過時間節約の合計。 |
| キャッシュによる時間節約を報告するビルド | `cache_time_saved_samples` | 有効な節約値を持つビルド。 |

Gradleプラグインは、ローカルおよびリモートのタスクキャッシュヒットに対して回避された推定作業量を自動的に報告します。各キャッシュされたタスクについて、Gradleが保存した元の実行時間からタスクの復元時間を差し引き、最小値をゼロとします。ビルドの見積もりはこれらの値を合計します。並列タスクは重複する可能性があるため、これは累積タスク時間であり、節約された経過ビルド時間ではありません。最新の状態のタスクとスキップされたタスクは除外されます。

タスクキャッシュヒットのないビルドはゼロを報告します。キャッシュされたタスクのいずれかに元の実行時間が欠けている場合、テレメトリが不完全な場合、またはカスタムメタデータマップに空きがない場合、プラグインは見積もりを省略します。古いプラグインバージョンや他のビルドシステムはこれを報告しません。カバレッジを確認するには、報告数と総ビルド数を比較してください。

報告された経過時間節約は`tuist.cache_time_saved_ms`メタデータから取得されます。このメトリクスは自動見積もりとは別個のままです。

どのビルドも報告しない場合、キャッシュによる節約には値がありません。Onceは現在この測定値を記録していません。キャッシュヒット率とミス率は、このデータソースでは利用できません。

### テーブル

これらの識別子は、クエリの`queryType`フィールドの値です。

| テーブル | クエリタイプ | 内容 |
| --- | --- | --- |
| ワークロード別の健全性 | `buildWorkloads` | ビルド数、成功率、中央値および90パーセンタイル時間。 |
| 失敗カテゴリ | `buildFailureReasons` | すべての失敗と失敗カテゴリごとの件数。 |
| 最近の失敗したビルド | `buildRecentFailures` | 最新の100件の失敗。Tuistへのリンク付き。 |

最近の失敗には、開始時間、期間、ユーザー、ブランチ、および要求されたタスクが含まれます。失敗カテゴリは`verification`、`infrastructure_tooling`、および`unknown`です。

ワークロードの概要とブランチ/ワークロードの値リストは最大1000件の値を返します。ビルド健全性の変数クエリは過去90日間を使用します。レガシーGradle変数クエリは既存の履歴ウィンドウを維持します。Bazelはツールによって報告されたビルドユーザーを表示します。他の統合は、報告資格情報に関連付けられたアカウントを表示します。記録されたユーザーがない場合、過去のBazelおよびOnceの実行、およびプロジェクト資格情報で報告されたOnceの実行は「不明」として表示されます。

ビルド実行の失敗カテゴリフィルターを使用して、一致する失敗を検索します。カテゴリはビルド詳細に表示され、その意味を説明する情報ヒントが付いています。デフォルトの概要およびビルド実行テーブルは既存の列を維持します。成功、キャンセル、および未完了のビルドには失敗カテゴリがありません。Gradleのキャッシュ分析カードとビルド詳細には「累積タスク時間の節約」が表示され、ツールチップには見積もりと並列タスクの影響が説明されています。キャッシュウィジェットは、選択した範囲を同じフィルターを使用した直前の同等の期間と比較します。比較は中立的です。合計が大きくなることは、より多くのビルドを反映している可能性があります。以前の見積もりが欠落している場合は比較が表示されません。記録されたゼロベースラインは、パーセンテージではなく絶対増加を示します。

## 標準ダッシュボード {#what-you-can-query}

[ビルド健全性ダッシュボード](https://github.com/tuist/tuist/blob/main/grafana-datasource/src/dashboards/build-health.json)をインポートし、データソースとプロジェクトを選択します。これには、ビルド数、成功率、中央値および90パーセンタイル時間、低速ビルドのしきい値、中立的な失敗または低速ビルド数、グループ化されたキャッシュ節約と報告カバレッジ、および3つの失敗およびワークロードテーブルが含まれます。必要に応じて、他の利用可能なメトリクスのパネルを追加します。自動低速しきい値は選択した期間自体の90パーセンタイルです。それを超えるビルドが必ずしも回帰を示すわけではありません。時間目標アラートのために固定しきい値を設定します。キャッシュパネルは、Gradleの自動累積タスク時間見積もりとそのカバレッジを優先し、次に明示的に報告された経過時間節約とそのカバレッジを表示します。

## ビルドシステム {#build-systems}

ビルド健全性クエリと標準ダッシュボードは、Bazel、Cargo、Once、Gradle、およびXcodeをサポートしています。Tuistはプロジェクトからビルドシステムを選択します。混合プロジェクトは、現在ビルド健全性クエリまたは標準ダッシュボードではサポートされていません。

| ビルドシステム | ワークロード | キャンセル報告 | キャッシュによる節約 |
| --- | --- | --- | --- |
| Bazel | コマンド | 終了コード8（`run`を除く） | カスタムメタデータが必要 |
| Cargo | コマンド | 区別されません。カウントはゼロです | 経過時間節約にはカスタムメタデータが必要です。コンパイラの作業回避は経過時間節約ではありません |
| Once | コマンド種別 | 記録されたキャンセル理由 | 記録されません |
| Gradle | タスクグループ | 報告されたキャンセル | 自動的な作業回避見積もり。経過時間節約にはカスタムメタデータが必要です |
| Xcode | スキーム | 区別されません。カウントはゼロです | カスタムメタデータが必要 |

処理中のレコードと未完了の実行は除外されます。Bazelには、ビルド、テスト、実行、およびカバレッジのコマンドが含まれます。Onceには、確定したビルド、テスト、および汎用実行が含まれます。Cargoには、`build`、`check`、`test-build`などのビルドコマンドが含まれます。レガシーなテスト実行レポートはビルド健全性から除外されます。Cargoの最近の失敗は、利用可能な場合は記録された開始時間を使用し、そうでない場合は挿入時間にフォールバックします。欠落している継続時間はゼロではなく、利用不可として扱われます。

Gradleは、優先順位の高い順に、インストゥルメント化されたテスト、ユニットテスト、リント/チェック、アセンブル/パッケージ、またはその他としてタスクをグループ化します。各ビルドは1つのワークロードに属します。カスタムメタデータは、Xcode、Bazel、Cargo、およびGradleのワークロードを上書きできます。

### 失敗カテゴリ

| カテゴリ | 意味 | 記録された証拠 |
| --- | --- | --- |
| `verification` | コードのコンパイル、リンク、テスト、またはチェックが失敗しました。 | Gradleの検証またはコンパイル例外および既知の失敗タスクタイプ。Xcodeのコンパイラおよびリンカーの問題。Bazelの構造化された非ゼロのコンパイラ/テストアクション結果。Cargoで記録された失敗したrustcコンパイル。Onceのテスト失敗、またはコンパイル、リンク、テスト、リント、チェックとして明示的に宣言された失敗したアクション。 |
| `infrastructure_tooling` | ツール、依存関係、または環境の失敗により、ビルドを正常に実行できませんでした。 | Gradleの設定、依存関係解決、入出力、またはメモリの失敗。Bazelの構造化されたインフラストラクチャの失敗および[文書化された終了コード](https://bazel.build/run/scripts)。Onceのインフラストラクチャアクションエラー。 |
| `unknown` | レポートには、失敗を分類するのに十分な証拠が含まれていません。 | 任意のコマンド、欠落している診断情報、および構造化された証拠のない古いレポート。 |

Gradleの設定フェーズの失敗（ビルドスクリプトのエラーを含む）は、タスク実行が進められなかったため、インフラストラクチャ/ツール配下にグループ化されます。

明示的なカテゴリメタデータまたは記録された失敗したrustcコンパイルのないCargoの失敗は`unknown`のままです。`check`または`test-build`コマンドの失敗だけでは、検証失敗とはみなされません。Cargoのタスク再利用カウンターおよび推定コンパイラ作業回避は、経過キャッシュ節約またはGradleの累積タスク時間メトリクスのいずれも提供しません。

明示的な`tuist.failure_category`メタデータは自動分類を上書きします。それ以外の場合、ビルド内で両方が発生した場合、インフラストラクチャの証拠が検証よりも優先されます。失敗した任意のスクリプトは、コンパイラまたはテストの失敗とはみなされません。過去のレポートは、Tuistがすでに保存している証拠を使用できますが、新しいレポーターフィールドは欠落している情報を後付けしません。自動レポーターメタデータは、既存の20エントリのカスタムメタデータ制限内の利用可能なスペースを使用します。

`buildFailureReasons`レスポンスは互換性のために`all`行を保持します。標準ダッシュボードは、その合計を失敗カテゴリチャートからフィルタリングし、合計失敗数を別に表示します。レガシーな`gradleFailureReasons`クエリは、元の3つのカテゴリ行を保持します。

## クエリオプション {#query-options}

数値クエリは、これらの`queryType`値を使用します。

| クエリ | クエリタイプ |
| --- | --- |
| ビルド健全性 | `buildHealth` |
| Xcodeビルド時間 | `buildDuration` |
| テスト時間 | `testDuration` |

`resultMode`フィールドは、結果の返却方法を制御します。

| 結果 | 値 | 動作 |
| --- | --- | --- |
| 時系列 | `series` | 各間隔の値。 |
| 全期間 | `total` | 範囲内のすべての実行から計算された1つの値。 |

フィルターラベルは、次のクエリフィールドに対応します：

| フィルター | クエリフィールド | 利用可能 |
| --- | --- | --- |
| 環境 | `environment` | すべてのクエリ |
| ブランチ | `gitBranch` | ビルド健全性クエリとテーブル |
| ワークロード | `workload` | ビルド健全性クエリとテーブル |
| ステータス | `status` | ビルド健全性クエリ、テーブル、およびXcode時間 |
| スキーム | `scheme` | Xcodeビルドおよびテスト時間 |
| 構成 | `configuration` | Xcodeビルド時間 |
| ビルドタイプ | `category` | Xcodeビルド時間 |

環境値は`any`、`ci`（自動ビルド）、および`local`です。ステータス値は`success`、`failure`、およびビルド健全性クエリの場合は`cancelled`です。値を省略すると、すべてのステータスが含まれます。ビルドタイプ値は`clean`および`incremental`です。値を省略すると、両方が含まれます。

空のビルド健全性間隔は、カウントがゼロで、平均時間、時間のパーセンタイル、または成功率の値がありません。低速ビルドのしきい値は、選択された全範囲を引き続き使用します。個別のテスト時間クエリは、空の時系列間隔に対してゼロを返します。全期間のパーセンタイルは、間隔のパーセンタイルではなく、実行から計算されます。ビルド健全性のパーセンタイルは正確な集計を使用します。個別のXcodeおよびテスト時間クエリは、近似パーセンタイルを使用します。

ビルド健全性の時系列は、選択された範囲の開始時に部分的な最初のバケットを配置して、表示されるようにします。レガシーなGradleクエリは、元のバケットタイムスタンプを保持します。

すべてのクエリは、最大366日間の日付範囲を受け入れます。境界とタイムスタンプは異なります：

| クエリ | 使用されるタイムスタンプ | 範囲の境界 |
| --- | --- | --- |
| ビルド健全性：Xcode、Bazel、Cargo、Gradle | 記録挿入時間 | 開始を含み、終了を除外 |
| ビルド健全性：Once | 実行開始時間 | 開始を含み、終了を除外 |
| Xcodeビルド時間 | 記録挿入時間 | 開始と終了を除外 |
| テスト時間 | 記録された実行時間 | 開始と終了を含む |

### ダッシュボード変数

プロジェクトおよびサポートされているフィルターにダッシュボード変数を使用します。ブランチとワークロードの変数は、次のクエリを使用します：

| 変数 | クエリ |
| --- | --- |
| ブランチ | `buildBranches account/project` |
| ワークロード | `buildWorkloads account/project` |

フィルターは1つの正確な値を受け入れます。ブランチとワークロードの変数については、「すべて」オプションのカスタム値を`__tuist_all__`に設定します。他のフィルターは、組み込みの「任意」オプションまたは空の値を使用します。複数選択と正規表現はサポートされていません。

## カスタムメタデータのレポート {#custom-metadata}

Xcode、Bazel、Cargo、およびGradleビルドは、次のオプションのメタデータ値を受け入れます：

| キー | 受け入れられる値 |
| --- | --- |
| `tuist.workload` | デフォルトのグループ化を置き換えるワークロード名。 |
| `tuist.failure_category` | `verification`または`infrastructure_tooling`。 |
| `tuist.cache_work_avoided_ms` | Gradleのみ。自動的にレポートされる作業回避見積もり（整数ミリ秒、最大365日）。 |
| `tuist.cache_time_saved_ms` | 0から31,536,000,000（365日）までの整数ミリ秒。 |

ビルド統合のカスタムメタデータ構成を通じてこれらを指定します：

```json
{
  "custom_metadata": {
    "values": {
      "tuist.workload": "Release verification",
      "tuist.failure_category": "verification",
      "tuist.cache_time_saved_ms": "12000"
    }
  }
}
```

経過時間の測定値またはそのビルドの文書化された見積もりがある場合にのみ、キャッシュ節約をレポートします。タスクが並行して実行される場合、キャッシュヒットと累積タスク時間だけでは経過節約を決定できません。欠落したキャッシュ節約は不明のままです。欠落した失敗カテゴリメタデータは、[ビルドシステム](#build-systems)で説明されているように、記録された証拠にフォールバックします。データ保持ポリシーは変更されません。

## アラートとSlack {#alerts-and-slack}

数値メトリックを使用してGrafana管理のアラートルールを作成します。例：

| メトリック | 識別子 | 条件の例 |
| --- | --- | --- |
| ビルド成功率 | `success_rate` | 99%未満 |
| 失敗したビルド | `failed_builds` | ゼロより大きい |
| 90パーセンタイル時間 | `p90` | チームの時間制限を超える |

評価ウィンドウ全体の単一値を取得するには**全期間**を使用するか、時系列を単一値に集約します。全期間モードの時間クエリの場合は、1つのシリーズを選択します。

- 固定されたプロジェクトとフィルターの値を使用します。バックグラウンドのアラート評価中は、ダッシュボード変数を使用できません。
- アラートには数値クエリを使用します。ワークロードを監視するには、ビルド健全性クエリをそのワークロードにフィルターします。
- ビルドや報告されたキャッシュ節約がない間隔に対するルールの「データなし」動作を設定します。

[Slackコンタクトポイント](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/configure-slack/)を構成し、Grafanaの通知ポリシーを通じてルールをそこにルーティングします。Grafanaが通知を送信し、Slackの認証情報を保存します。

## 既存のダッシュボードのアップグレード {#upgrading}

既存の時間パネルは、クエリ、フィルター、シリーズ名、および単位を保持します。保存されたGradle健全性パネルと変数も引き続き機能します。

共有ビルド健全性クエリを使用するには、標準ダッシュボードを個別にインポートします。既存のダッシュボードは自動的に移行されません。共有クエリには、ビルド健全性エンドポイントを提供するTuistサーバーが必要です。既存の時間クエリは、古いサーバーでも引き続き機能します。

## 要件 {#requirements}

- Grafana 10.4以降。
- チャート化したいプロジェクトとメトリックを読み取る権限を持つTuistトークン。以下の[認証](#authentication)を参照してください。

## 認証 {#authentication}

ダッシュボードとバックグラウンドのアラート評価には、<.localized_link href="/guides/server/authentication#account-tokens">アカウントトークン</.localized_link>を使用します。ビルドメトリックには`project:builds:read`を、テスト時間には`project:tests:read`を付与し、チャート化したいプロジェクトへのアクセスを制限します。使用するメトリックに必要なスコープのみが必要です。<.localized_link href="/guides/server/authentication#creating-an-account-token">トークン作成手順</.localized_link>に従って生成してください。

この統合は、既存のプロジェクトトークンをそのプロジェクト向けに受け入れ、またユーザーの読み取り権限を持つ<.localized_link href="/guides/server/authentication#as-a-user">ユーザーアクセストークン</.localized_link>も受け入れます。ユーザーアクセストークンは短寿命です。Grafanaは提供されたトークンを保存しますが、更新したりローカルのTuistログインを再利用したりしません。有効期限が切れたら交換してください。アカウントトークンを使用すると、ユーザーのログインセッションとは独立して、プロジェクトへのアクセス、権限、および有効期限を制御できます。

## 構成 {#configuration}

データソースを追加して設定します：

| フィールド | 保存される設定 | 備考 |
| --- | --- | --- |
| サーバーURL | `jsonData.url` | デフォルトは`https://tuist.dev`です。 |
| トークン | `secureJsonData.apiToken` | Tuistベアラートークン。暗号化されて保存されます。 |

**保存してテスト**を選択して接続を確認します。Grafanaはアクセス可能なプロジェクトを一覧表示し、最初のプロジェクトに対してビルドおよびテストの読み取り権限をチェックします。

## インストール {#installation}

### Grafanaカタログから {#from-the-grafana-catalog}

公開されると、**Connections → Add new connection → Tuist**から他のデータソースと同様にインストールするか、`grafana-cli plugins install tuist-metrics-datasource`を使用してインストールします。

### 公開前（セルフホスト型Grafana） {#before-it-is-published-self-hosted-grafana}

プラグインはカタログで承認されるまで署名されていません。セルフホスト型インスタンスでは、次のいずれかを実行できます：

- **署名なしで許可** — `allow_loading_unsigned_plugins`（または`GF_PLUGINS_ALLOW_LOADING_UNSIGNED_PLUGINS=tuist-metrics-datasource`）に`tuist-metrics-datasource`を追加し、ビルドされたプラグインをプラグインディレクトリに配置します。
- インスタンス用に**プライベートに署名** — `npm run sign -- --rootUrls https://grafana.example.com`（URLはインスタンスの`root_url`と一致する必要があります）。その後、zipファイルを配布します。

[Grafana Cloudではカタログからのプラグインが必要](https://grafana.com/docs/grafana-cloud/learn-and-build/get-started/learn/find-and-use-plugins/)であり、署名されていないプラグインや手動でアップロードされたプラグインはサポートされていません。
