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

This product is not supported for your selected Datadog site. ().

概要

このガイドでは、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 を送信すると、ユーザーインターフェイスが意図しない動作を示す場合があります。たとえば、フレームグラフに別のパイプライン実行のスパンタグが表示されることがあります。同一のタイムスタンプで重複した 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 情報のないパイプライン実行は、最近のコード変更ページ に表示されません。最低限、リポジトリの URL、コミット SHA、および作者のメールアドレスが必要です。詳細については、公開 API エンドポイント仕様 を参照してください。

##参考資料

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

Pipeline Visibility についてDOCUMENTATION more more