概要

このガイドでは、CI Visibility でパイプライン実行をプログラムで設定する方法を説明し、CI Visibility がサポートするパイプライン実行のタイプを定義します。

このガイドは、公開 CI Visibility Pipelines API を使用して作成されたパイプラインに適用されます。他の CI プロバイダとのインテグレーションは異なる場合があります。

データモデル

パイプラインの実行は、APM の分散トレースと同様にトレースとしてモデル化され、スパンがパイプラインの各部分の実行を表します。CI Visibility でパイプライン実行を表すデータモデルは、4 つのレベルで構成されます。

パイプライン、ステージ、ジョブ、ステップが終了すると、実行データが Datadog に送信されます。Pipeline Visibility を設定するには、サポートされている CI プロバイダーのリストを参照してください。CI プロバイダーまたはワークフローがサポートされていない場合は、公開 API エンドポイントを使用してパイプラインの実行データを CI Visibility に送信できます。

ステージ、ジョブ、ステップは、親となるパイプラインとまったく同じパイプライン名であることが期待されます。名前が一致しない場合、一部のパイプラインでステージやジョブ、ステップの情報が欠ける可能性があります。たとえば、ジョブサマリーのテーブルにジョブが表示されない場合などです。

パイプライン固有 ID

同じレベル内のすべてのパイプライン実行は、一意の識別子を持たなければなりません。たとえば、パイプラインとジョブが同じ一意 ID を持つことは可能ですが、2 つのパイプラインが同じ一意 ID を持つことはできません。

異なるタイムスタンプで同じ ID を送信すると、ユーザーインターフェイスが意図しない動作を示す場合があります。たとえば、フレームグラフに別のパイプライン実行のスパンタグが表示されることがあります。また、同一のタイムスタンプで重複した ID を送信すると、最後に受信したパイプライン実行の値のみが保存されます。

パイプライン実行タイプ

通常の実行

パイプラインの通常の実行は、以下のフローに従います。

プロバイダーによっては、いくつかのレベルが欠落している場合があります。例えば、ステージは存在しないかもしれませんし、ジョブは並行して実行されるかもしれませんし、順番に実行されるかもしれません。

各コンポーネントの完了後、実行を表すために必要な全てのデータを含むペイロードを Datadog に送信する必要があります。Datadog はこのデータを処理し、パイプラインイベントとして保存し、CI Visibility に表示します。パイプラインの実行は Datadog に送信する前に終了する必要があります。

完全なリトライ

パイプラインを完全にリトライする場合は、リトライごとに異なるパイプラインの一意の ID を使用する必要があります。

公開 API エンドポイントでは、previous_attempt フィールドを設定して以前のリトライと関連付けることができます。Datadog 上ではリトライは別のパイプライン実行として扱われ、開始時刻と終了時刻はそのリトライに対応する範囲のみを含みます。

部分的なリトライ

パイプライン内のジョブのサブセットをリトライする場合は、新しいパイプライン固有 ID を持つ新しいパイプラインイベントを送信する必要があります。新しいジョブのペイロードは、新しいパイプライン固有 ID にリンクされていなければなりません。前回のリトライとリンクさせるには、previous_attempt フィールドを追加します。

部分リトライも同様に別のパイプラインとして扱われます。開始時刻と終了時刻には、元のパイプライン実行の時間を含めてはいけません。部分リトライでは、前回の実行で実行されたジョブのペイロードは送信しないでください。また、実行時間を集計する際に部分リトライを除外するため、部分リトライの場合は partial_retry フィールドを true に設定します。

例えば、P という名前のパイプラインには J1、J2、J3 という 3 つのジョブがあり、順次実行されます。P の最初の実行では、J1 と J2 のみが実行され、J2 は失敗します。

したがって、合計 3 つのペイロードを送信する必要があります。

1. J1 のジョブペイロード。ID は J1_1、パイプライン ID は P_1。
2. J2 のジョブペイロード。ID は J2_1、パイプライン ID は P_1。
3. P のパイプラインペイロード。ID は P_1。

J2 から始まるパイプラインの部分的なリトライがあり、残りのジョブがすべて成功したとします。

さらに 3 つのペイロードを送信する必要があります。

1. J2 のジョブペイロード。ID は J2_2、パイプライン ID は P_2。
2. J3 のジョブペイロード。ID は J3_1、パイプライン ID は P_2。
3. P のパイプラインペイロード。ID は P_2。

ID の実際の値自体は重要ではありません。重要なのは、上記のとおりパイプラインの実行に応じて適切に変更されていることです。

ブロッ クされたパイプライン

パイプラインが手動介入を必要とするために無期限にブロックされる場合、パイプラインがブロッ クされた状態になるとすぐにパイプラインイベントペイロードを送信しなければなりません。パイプラインのステータスは blocked に設定されていなければなりません。

残りのパイプラインデータは、異なるパイプラインの一意 ID を用いて別のペイロードで送信する必要があります。2 つ目のパイプラインでは、ブロックされたパイプラインから再開されたことを示すために is_resumed を true に設定できます。

ダウンストリームパイプライン

パイプラインが他のパイプラインの子としてトリガーされた場合、parent_pipeline フィールドには親パイプラインの詳細を入力する必要があります。

手動パイプライン

パイプラインが手動でトリガーされる場合、is_manual フィールドを true に設定する必要があります。

Git 情報

パイプライン実行をトリガーしたコミットの Git 情報を提供することが強く推奨されます。Git 情報のないパイプライン実行は Recent Code Changes ページに表示されません。最低限、リポジトリの URL、コミット SHA、および作者のメールアドレスが必要です。詳細は公開 API エンドポイント仕様を参照してください。

参考資料

お役に立つドキュメント、リンクや記事:

Pipeline Visibility についてDOCUMENTATION