パイプラインのデータモデルと実行タイプ

選択したサイト () では CI Visibility は利用できません。

概要

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

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

データモデル

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

レベル名説明
パイプライン (必須)他のすべてのレベルを子として含む、最上位のルートスパン。パイプラインの開始から終了までの全体的な実行を表します。CI プロバイダーによっては、このレベルを build や workflow と呼ぶこともあります。
ステージユーザー定義の名前の下でジョブをグループ化する役割を果たします。CI プロバイダーによっては、このレベルはありません。
ジョブコマンドが実行される最小の作業単位。このレベルのタスクはすべて 1 つのノードで実行する必要があります。
手順CI プロバイダーによっては、このレベルはシェルスクリプトやジョブ内で実行されるアクションを表します。

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

パイプライン実行トレースの例

ステージ、ジョブ、ステップは、親のパイプラインと全く同じパイプライン名を持つことが想定されています。不一致があった場合、一部のパイプラインでステージ、ジョブ、ステップの情報が欠ける可能性があります。たとえば、ジョブサマリーテーブルでジョブが欠落したりします。

パイプライン固有 ID

レベル内のすべてのパイプライン実行には一意の識別子が必要です。例えば、パイプラインとジョブは同じ一意の ID を持つことができますが、2 つのパイプラインは持つことができません。

タイムスタンプが異なる ID を繰り返し送信すると、ユーザーインターフェイスが望ましくない動作を示すことがあります。例えば、フレームグラフには別のパイプライン実行からのスパンタグが表示される可能性があります。同じタイムスタンプの ID が重複して送信された場合、1 つのパイプライン実行のみが保存され、他は無視されます。

パイプライン実行タイプ

通常の実行

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

通常のパイプライン実行の描写

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

各コンポーネントの完了後、実行を表すために必要な全てのデータを含むペイロードを 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 情報のないパイプライン実行は My Recent Commits ページに表示されません。最低限、リポジトリの URL、コミットの SHA、作成者のメールアドレスが必要です。詳細については、公開 API エンドポイント仕様を参照してください。

その他の参考資料

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

Pipeline Visibility についてDOCUMENTATION more more