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

概要

CI Visibility を有効にすると、CI Pipeline または CI Test モニターを作成することができます。

CI モニターでは、CI データを視覚化し、それに対するアラートを設定することができます。例えば、CI Pipeline モニターを作成し、パイプラインやジョブが失敗した場合のアラートを受信します。CI Test モニターを作成し、失敗したテストや遅いテストに関するアラートを受信します。

モニターの作成

Datadog で CI モニターを作成するには、メインナビゲーションで Monitors -> New Monitor –> CI の順に進みます。

: アカウント当たり上限 1000 件の CI モニターがデフォルトで設定されています。この制限を解除するには、サポートまでお問い合わせください。

Pipelines または Tests のどちらかのモニターを選択します。

検索クエリを定義する

  1. CI エクスプローラーでの検索と同じロジックを使用して検索クエリを作成します。
  2. CI パイプラインイベントのレベルを選択します。
    • Pipeline: 通常、1 つ以上のジョブで構成されるパイプライン全体の実行を評価します。
    • Stage: 1 つ以上のジョブのグループをサポートする CI プロバイダーでの実行を評価します。
    • Job: コマンド群の実行を評価します。
    • Command: ジョブで実行される個々のコマンドである、手動でインスツルメントされたカスタムコマンドイベントを評価します。
    • All: あらゆる種類のイベントを評価します。
  3. CI パイプラインのイベント数、ファセット、またはメジャーのモニタリングを選択します。
    • CI Pipeline event count: 検索バーを使用し (任意)、ファセットまたはメジャーは選択しません。選択されたタイムフレームで Datadog が CI パイプラインイベント数を評価し、それをしきい値の条件と比較します。
    • Dimension: ディメンション (質的ファセット) を選択し、そのファセットの Unique value count に対してアラートを表示します。
    • Measure: CI Pipeline メジャーの数値に対してアラートを出すためのメジャー (定量ファセット) を選択します (メトリクスモニターに似ています)。集計方法 (minavgsummedianpc75pc90pc95pc98pc99、または max) を選択します。
  4. 複数のディメンションで CI パイプラインイベントをグループ化する (オプション):
    • クエリに一致するすべての CI パイプラインイベントは、最大 4 つのファセットの値に基づいてグループに集約されます。
  5. アラート設定のグループ化方法を構成します(任意):
    • クエリに group by が含まれる場合、グループパラメーターに従い、複数のアラートを各ソースに適用します。アラートイベントは、設定された条件を満たすと各グループに生成されます。たとえば、クエリを @ci.pipeline.name でグループ化すると、エラーの数が多い場合に CI パイプラインごとに個別のアラートを受信することができます。
テスト名でグループ化されるよう設定される CI Status:Error のクエリ

数式と関数の使用

数式と関数を使用して CI パイプラインを作成できます。これは、たとえばパイプラインの失敗率(エラー率)など、イベントの発生のモニターを作成する場合に使用できます。

次の例は、ci.pipeline.name (パイプラインごとに 1 回アラートする) でグループ化された “全パイプラインイベント数” (フィルターなし) に対する “失敗パイプラインイベント数” (ci.status=error) の割合を計算する式を使ったパイプラインエラー率モニターの例です。詳しくは、関数の概要を参照してください。

モニターは、ステップ a、b、c で定義され、ステップ a と b はクエリし、ステップ c はそれらからレートを計算します。
: 各モニターに評価数式の構築には、最大 2 つのクエリまで使用できます。

検索クエリを定義する

  1. 共通モニタータイプ: (オプション) New Flaky TestTest FailuresTest Performance 共通モニタータイプごとにテンプレートクエリを提供し、カスタマイズすることが可能です。この機能の詳細については、新しい不安定なテストの追跡を参照してください。
  2. CI Test エクスプローラーの検索と同じロジックで検索クエリを作成します。たとえば、myapp というテストサービスの main ブランチに対して失敗したテストを検索するには、クエリ @test.status:fail @git.branch:main @test.service:myapp を使用します。
  3. CI Test のイベント数、ファセット、またはメジャーのモニタリングを選択します。
    • CI Test event count: 検索バーを使用し (任意)、ファセットまたはメジャーは選択しません。選択されたタイムフレームで Datadog が CI パイプラインテストイベント数を評価し、それをしきい値の条件と比較します。
    • Dimension: ディメンション (質的ファセット) を選択し、そのファセットの Unique value count に対してアラートを表示します。
    • Measure: CI Pipeline ファセットの数値に対してアラートを出すためのメジャー (定量ファセット) を選択します (メトリクスモニターに似ています)。集計方法 (minavgsummedianpc75pc90pc95pc98pc99、または max) を選択します。
  4. 複数のディメンションで CI Test イベントをグループ化する (オプション):
    • All CI Test events matching the query are aggregated into groups based on the value of up to four facets.
  5. アラート設定のグループ化方法を構成します(任意):
    • If the query has a group by, an alert is sent for every source according to the group parameters. An alerting event is generated for each group that meets the set conditions. For example, you could group a query by @test.full_name to receive a separate alert for each CI Test full name when the number of errors is high. Test full name is a combination of a test suite and test name, for example: MySuite.myTest. In Swift, test full name is a combination of a test bundle, and suite and name, for example: MyBundle.MySuite.myTest.
パイプライン名でグループ化されるよう設定される CI Status:Error のクエリ

異なるパラメーターや構成でのテスト実行

同じテストのフルネームで、異なるテストパラメーターや構成のテストがある場合、モニターの group by@test.fingerprint を使用します。こうすることで、特定のパラメーターや構成でテストを実行した場合に警告を発することができます。@test.fingerprint を使用すると、Commit Overview ページにある Test Stats, Failed and Flaky Tests セクションと同じ粒度レベルが提供されます。

例えば、同じフルネームのテストが Chrome では失敗し、Firefoxでは合格した場合、フィンガープリントを使用すると、Chrome のテスト実行時にのみアラートが発生します。

Using @test.full_name in this case triggers the alert, even though the test passed on Firefox.

数式と関数

数式と関数を使用して CI Test を作成できます。たとえば、これはテストの失敗率 (エラー率) など、イベントの発生のモニターを作成する場合に使用できます。

以下は、テストエラー率モニターの例です。「テストイベント総数」(フィルターなし) に対する「失敗したテストイベント」(@test.status:fail) の割合を計算する数式を使用し、@test.full_name でグループ化 (テストごとにアラート) されています。詳しくは、関数の概要をご覧ください。

ステップ a、b、c で定義されたモニター。ステップ a および b はクエリで、ステップ c はそこから割合を算出します。

CODEOWNERS を利用した通知

テストイベントで利用可能な CODEOWNERS の情報を使って、異なるチームに通知を送信することができます。

以下の例では、次のロジックで通知を構成しています。

  • もしテストコードのオーナーが MyOrg/my-team ならば、my-team-channel Slack チャンネルに通知を送ります。
  • もしテストコードのオーナーが MyOrg/my-other-team ならば、my-other-team-channel Slack チャンネルに通知を送ります。
{{#is_match "citest.attributes.test.codeowners" "MyOrg/my-team"}}
  @slack-my-team-channel
{{/is_match}}
{{#is_match "citest.attributes.test.codeowners" "MyOrg/my-other-team"}}
  @slack-my-other-team-channel
{{/is_match}}

モニターの Notification message セクションに、上記のコードスニペットのようなテキストを追加して、モニター通知の設定をします。is_match 句は必要なだけ追加することができます。Notification 変数については、条件付き変数の監視を参照してください

アラートの条件を設定する

  • メトリクスが aboveabove or equal tobelowbelow or equal to の場合にトリガーされる
  • 過去 5 minutes15 minutes1 hour の間のしきい値、または custom1 minute2 days の値を設定します。
  • アラートのしきい値 <数値>
  • 警告のしきい値 <数値>

高度なアラート条件

高度なアラートオプション (評価遅延など) の詳細な手順については、モニターコンフィギュレーションページを参照してください。

通知

For detailed instructions on the Configure notifications and automations section, see the Notifications page.

ログのサンプルと違反値トップリスト

CI テストまたはパイプラインモニターがトリガーされると、サンプルまたは値が通知メッセージに追加されます。

モニター設定通知メッセージに追加可能な値
グループ化されていない Simple-Alert 数最大 10 個のサンプル。
グループ化された Simple-Alert 数最大 10 個のファセット値またはメジャー値。
グループ化された Multi-Alert 数最大 10 個のサンプル。
グループ化されていない Simple-Alert メジャー最大 10 個のサンプル。
グループ化された Simple-Alert メジャー最大 10 個のファセット値またはメジャー値。
グループ化された Multi-Alert メジャー最大 10 個のファセット値またはメジャー値。

これらの通知の送信に、Slack、Jira、webhooks、Microsoft Teams、Pagerduty、電子メールを使用することができます。: サンプルはリカバリ通知には表示されません。

サンプルを無効にするには、Say what’s happening セクションの一番下にあるチェックボックスをオフにします。チェックボックスの隣に表示されるテキストは、モニターのグループ化によって変わります(上記を参照)。

Sample examples

アラート通知に CI テスト 10 サンプルのテーブルを含めます。

CI テストサンプルトップ 10

アラート通知に CI パイプライン 10 サンプルのテーブルを含めます。

CI Pipeline サンプルトップ 10

データがない時の通知行動

評価クエリにイベントカウントを使用するモニターは、指定された評価期間の後にデータがなく解決され、通知をトリガーします。例えば、5 分の評価ウィンドウでパイプラインエラーの数にアラートするように構成されたモニターは、パイプラインの実行がない 5 分後に自動的に解決されます。

代替案として、Datadog はレートフォーミュラの使用を推奨しています。例えば、パイプラインの失敗数 (カウント) のモニターを使う代わりに、(パイプラインの失敗数)/(全パイプライン実行数) のようなパイプライン失敗の割合 (式) のモニターを使います。この場合、データがないときには分母の (全パイプライン実行数)0 となり、割り算 x/0 は評価できません。モニターは 0 に評価する代わりに、以前の既知の状態を維持します。

This way, if the monitor triggers because there’s a burst of pipeline failures that makes the error rate go above the monitor threshold, it will not clear until the error rate goes below the threshold, which can be at any time afterwards.

モニター例

一般的なモニターの使用例を以下に示します。モニタークエリは、特定のブランチ、作成者、その他のアプリ内のファセットに対してフィルターをかけるように変更することができます。

パフォーマンス低下のアラートをトリガーする

duration メトリクスは、パイプラインやテストのパフォーマンス低下を特定するために使うことができます。このメトリクスでアラートを出すことで、コードベースへのパフォーマンス後退を防ぐことができます。

CI パイプラインの低下モニター

新しい不安定なテストを追跡する

テストモニターには、New Flaky TestTest FailuresTest Performance という共通のモニタータイプがあり、簡単にモニターを設定することができます。このモニターは、新しい不安定なテストがコードベースに追加されたときにアラートを送信します。クエリは Test Full Name によってグループ化されているので、同じ新しい不安定なテストに対して何度もアラートが送られることはありません。

テスト実行が何度か再試行された後、同じコミット内で不安定性が発生した場合、flaky とマークされます。もし複数回不安定性が発生した場合 (複数のリトライが実行されたため)、is_flaky タグは不安定として検出された最初のテストランに追加されます。

同じブランチやデフォルトブランチ内でそのテストが不安定であると検出されていない場合、そのテスト実行は new flaky としてマークされます。新しい不安定として検出された最初のテスト実行だけが、(再試行の回数に関係なく) is_new_flaky タグでマークされます。

CI の不安定なテストモニター

詳しくは、CI テストの検索と管理を参照してください。

コードカバレッジ率の維持

コードカバレッジ率などのカスタムメトリクスを作成し、モニター内で使用することができます。以下のモニターは、コードカバレッジが一定の割合以下になるとアラートを送信し、長期間にわたってテストのパフォーマンスを維持するのに役立ちます。

CI の不安定なテストモニター

詳しくは、コードカバレッジを参照してください。

その他の参考資料