APM デプロイ追跡 は、DORA Metrics のデプロイのデータソースとして構成できます。

要件

• APM Deployment Tracking が DORA 設定 の Deployments イベントデータソースとして有効になっていること。
• サービスの メタデータ が Software Catalog で定義されていること。
• サービスの unified service tagging が有効になっていること。デプロイは version タグを使用して識別されます。

APM によって追跡されるサービスデプロイが変更リードタイムに確実に寄与するための詳細については、Enrich deployments with commit information を参照してください。

独自のデプロイイベントを送信するには、DORA Metrics API または datadog-ci dora deployment コマンドを使用します。

要件

• datadog-ci CLI / API は、DORA 設定 において Deployments イベントデータソースとして有効になっていること。
• 必須の属性は以下のとおりです。
  • started_at: デプロイの開始時刻
  • finished_at: デプロイの終了時刻
  • service: デプロイされたサービス提供されたサービスが、Software Catalog にメタデータがセットアップ (メタデータの追加 を参照) されて登録されている場合、サービスの team が自動的に取得され、すべてのメトリクスに関連付けられます。

オプションで以下の属性をデプロイイベントに追加できます。

• repository_url: サービスのソースコードリポジトリ変更リードタイムを計算するために必要です。
• commit_sha: デプロイに関連付けられた HEAD コミットの SHA です。変更リードタイムを計算するために必要です。
• team: サービスに自動的に見つかったものとは異なる team にデプロイを関連付けます。
• env: DORA Metrics ページで環境ごとに DORA Metrics をフィルタリングします。
• id: デプロイを特定します。この属性はユーザーが生成するもので、指定しない場合は、Datadog が生成する UUID がエンドポイントによって返されます。
• version: デプロイのバージョンです。
• custom_tags: DORA Metrics ページでイベントをフィルタリングする際に使用可能な key:value 形式のタグです。

API (cURL) の例

完全な仕様および追加のコードサンプルについては、DORA Metrics API リファレンスドキュメント をご覧ください。

次の例では、URL の <DD_SITE> を以下に置き換えます。 また ${DD_API_KEY} をユーザーの Datadog API キー に置き換えます。

  curl -X POST "https://api.<DD_SITE>/api/v2/dora/deployment" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -d @- << EOF
  {
    "data": {
      "attributes": {
        "service": "shopist",
        "started_at": 1693491974000000000,
        "finished_at": 1693491984000000000,
        "git": {
          "commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
          "repository_url": "https://github.com/organization/example-repository"
        },
        "env": "prod",
        "team": "backend",
        "version": "v1.12.07",
        "custom_tags": ["department:engineering", "app_type:backend"]
      }
    }
  }
EOF

CLI の例

datadog-ci CLI ツールは、ユーザーの Continuous Integration 環境内でデプロイイベントを送信するためのショートカットを提供します。

次の例では、DD_SITE 環境変数を以下に設定します。 また DD_API_KEY 環境変数をユーザーの Datadog API キー に設定します。

export DD_SITE="<DD_SITE>"
export DD_API_KEY="<DD_API_KEY>"

export deploy_start=`date +%s`
./your-deploy-script.sh
datadog-ci dora deployment --service shopist --env prod \
    --started-at $deploy_start --finished-at `date +%s` \
    --version v1.12.07 --custom-tags department:engineering \
    --custom-tags app_type:backend \
    --git-repository-url "https://github.com/organization/example-repository" \
    --git-commit-sha 66adc9350f2cc9b250b69abddab733dd55e1a588

デプロイの終了時刻は、--finished-at で指定されない場合、自動的に現在の時刻に設定されます。

デプロイ CI ジョブがデプロイされている正確に同じ Git リビジョンで実行されている場合、git-repository-url と git-commit-sha は省略可能であり、CI コンテキストから自動的に推測されます。

--skip-git オプションを提供することで、リポジトリの URL とコミット SHA の送信を無効にできます。このオプションが追加されると、変更リードタイムメトリクスは利用できなくなります。

APM デプロイ追跡を通じて特定されたデプロイの場合、ユーザーのアプリケーションのテレメトリに Git 情報がタグ付けされていることを確認してください。

• APM で Git のタグ付けを有効化します。または、ソースコード統合のドキュメント を参照してください。

注: APM で追跡されたデプロイの場合、変更リードタイムはコミットの作成から新しいバージョンでコミットが最初に観測されるまでの時間として計算されます。Deploy Time メトリクスは利用できません。

DORA Metrics API または datadog-ci dora deployment コマンドで追跡されたデプロイの場合、次のことを確認してください：

• 属性 repository_url と commit_sha が、デプロイイベントのペイロードに含まれています。

GitHub インテグレーション がまだインストールされていない場合は、GitHub インテグレーションタイル にインストールしてください。

GitHub アプリケーションの構成時:

1. Contents と Pull Requests に対して、少なくとも Read リポジトリ権限を選択してください。
2. 少なくとも Push、PullRequest、および PullRequestReview の各イベントに登録してください。

セットアップが有効であることを確認するには、GitHub インテグレーションタイル で GitHub アプリケーションを選択し、Datadog Features テーブルが Pull Request Information のすべての要件を満たしていることを確認してください。

GitLab ソースコードインテグレーション がまだインストールされていない場合は、GitLab ソースコードインテグレーションタイル にインストールしてください。

注: サービスアカウントの個人アクセストークンのスコープは、少なくともread_api である必要があります。

GitLab グループおよびサブグループの取り扱い

リポジトリが GitLab グループまたはサブグループ の下に整理されている場合 (たとえば、 https://gitlab.com/my-org/group(/subgroup)/repo)、 自動サービスパス検出は、GitLab のネストされたグループ構造が原因で正しく解決されない可能性があります。

DORA Metrics がサービスのソースコードパスを確実に正しく処理するように、 サービス定義に次の構成を使用できます。

extensions:
  datadoghq.com/dora-metrics:
    source_patterns:
      # All paths relative to the repository URL provided with the deployment
      - **
      # or specific paths related to this service (for monorepos)
      - src/apps/shopist/**
      - src/libs/utils/**

Azure DevOps ソースコードインテグレーション がまだインストールされていない場合は、Azure DevOps ソースコードインテグレーションタイル にインストールしてください。

統合を設定するには:

1. Datadog で Azure DevOps ソースコードインテグレーションタイル を開きます。

2. Configuration タブを選択し、Connect Microsoft Entra App をクリックします。

3. セットアップ手順に従います。

4. Add Organizations をクリックします。

5. リポジトリのインストール手順に従い、セットアップスクリプトを実行 してください。スクリプトが実行されない場合、プルリクエストが作成される前に行われたコミットが、そのプルリクエストに関連付けられることはありません。

6. スクリプトの完了後、タイル上で統合ステータスを確認してください。接続されたリポジトリとプロジェクトがリストに表示されます。

datadog-ci git-metadata upload コマンドを使用して、Git リポジトリのメタデータをアップロードできます。 このコマンドが実行されると、Datadog はリポジトリの URL、現在のブランチのコミット SHA、および追跡したファイルのパスのリストを受け取ります。

新しいコミットごとに CI でこのコマンドを実行してください。特定のコミット SHA に対してデプロイが実行される場合、必ずデプロイイベントが送信される前に、そのコミットに対して datadog-ci git-metadata upload コマンドを実行してください。

コマンドの正しいセットアップは、コマンド出力を確認することで検証できます。正しい出力の例を以下に示します。

Reporting commit 007f7f466e035b052415134600ea899693e7bb34 from repository git@github.com:organization/example-repository.git.
180 tracked file paths will be reported.
✅  Handled in 0.077 seconds.

DORA Metrics は、Datadog インシデント を通じて障害を自動的に特定し、追跡することができます。インシデントが宣言された後、DORA はそれらを使用して変更障害率と復旧時間を測定します。

注: 復旧時間は、インシデントがactive 状態にある合計時間として測定されます。active → stable → active → stable のようなケースでは、すべての active 期間が含まれます。復旧時間は、インシデントが stable または resolved 状態にあるときにのみ表示されます。resolved インシデントが再びアクティブ化されると、メトリクスは再び resolved になるまで非表示になります。

要件

• Incidents が DORA 設定 の Failures イベントデータソースとして有効になっていること。

ラベルのない障害を避けるために、Datadog はインシデントに次の属性を追加することを強く推奨します。

• Teams
• Services
• Envs: Envs 属性は、インシデント設定 ですでに存在しない場合に追加できます。

インシデントが提供されると、Severity タグが障害イベントに追加されます。

推奨: インシデント設定 で、属性フィールド Prompted を At Resolution に設定して、ユーザーのインシデントにこれらの属性を追加するのを決して忘れないようにしてください。

過去のインシデントを含める

DORA 設定 で Backfill Data を選択することで、過去 2 年間のインシデントをさかのぼって含めることができ、こうするとそれらのインシデントから障害が作成されます。データのバックフィリングには、最大 1 時間かかる場合があります。

PagerDuty は、IT チームにインシデントの即時可視性を提供し、運用上の安定性と回復力を維持するための積極的かつ効果的な対応を可能にするインシデント管理プラットフォームです。

PagerDuty アカウントを DORA Metrics に統合するには:

1. DORA 設定 で PagerDuty を Failures イベントデータソースとして有効にします。

2. PagerDuty で、Integrations > Developer Tools に移動し、Generic Webhooks (v3) をクリックします。

 <table>
  <thead>
    <tr>
      <th>変数</th>
      <th>説明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Webhook の URL</td>
      <td>追加 <code>https://webhook-intake.<span class="js-region-param region-param" data-region-param="dd_site"></span>/api/v2/webhook/</code>.</td>
    </tr>
    <tr>
      <td>スコープタイプ</td>
      <td>送信したいインシデントのスコープを選択してください。特定の <span class="ui">Service</span> または <span class="ui">Team</span>、またはユーザーの <span class="ui">Account</span> 内のすべての PagerDuty サービスのインシデントを送信できます。環境やアクセスレベルによっては、一部のスコープタイプが利用できない場合があります。</td>
    </tr>
    <tr>
      <td>説明</td>
      <td>説明は Webhook を区別する上で役立ちます。次のようなものを追加します <code>Datadog DORA Metrics integration</code>.</td>
    </tr>
    <tr>
      <td>イベントサブスクリプション</td>
      <td>次のイベントを選択してください。<br>-<code>incident.acknowledged</code><br>-<code>incident.annotated</code><br>-<code>incident.custom_field_values.updated</code><br>-<code>incident.delegated</code><br>-<code>incident.escalated</code><br>-<code>incident.priority_updated</code><br>-<code>incident.reassigned</code><br>-<code>incident.reopened</code><br>-<code>incident.resolved</code><br>-<code>incident.triggered</code><br>-<code>incident.unacknowledged</code></td>
    </tr>
    <tr>
      <td>カスタムヘッダー</td>
      <td><span class="ui">Add custom header</span> をクリックして、以下を名前として入力してください。 <code>DD-API-KEY</code> 値に <a href="https://docs.datadoghq.com/api/latest/authentication/#api-keys">Datadog API キー</a>を入力します。<br><br>オプションとして、Webhook から送信されたすべての PagerDuty インシデントに環境を追加するには、以下の名前の追加のカスタムヘッダーを作成できます。 <code>dd_env</code> さらに希望する環境を値として入力します。</td>
    </tr>
  </tbody>
</table>

1. Webhook を保存するには、Add Webhook をクリックします。

DORA Metrics 製品における障害の重大度は、PagerDuty の インシデント優先度 に基づきます。

**注:**Webhook 作成時に新しいシークレットが作成され、すべての Webhook ペイロードに署名するために使用されます。そのシークレットは統合が機能するために必要ではなく、認証は代わりに API キーを使用して行われます。

PagerDuty サービスを Datadog サービスにマッピングする

特定の PagerDuty サービス に対してインシデントイベントが受信されると、Datadog はトリガーされた Datadog モニター および Software Catalog から関連する Datadog サービスとチームを取得しようと試みます。

一致するアルゴリズムは、以下のステップで機能します。

1. PagerDuty インシデントイベントが Datadog モニターからトリガーされた 場合:

   • モニターが マルチアラートモード の場合、インシデントメトリクスとイベントは、アラートが発生したグループからの env、service、および team と共に発行されます。
   • モニターに env、service、または team の タグ がある場合:
     • env: モニターに単一の env タグがある場合、インシデントメトリクスとイベントは環境と共に発行されます。
     • service: モニターに 1 つ以上の service タグがある場合、インシデントメトリクスとイベントは提供されたサービスと共に発行されます。
     • team: モニターに単一の team タグがある場合、インシデントメトリクスとイベントはチームと共に発行されます。

2. インシデントのサービス URL が Software Catalog 内の任意のサービスの PagerDuty サービス URL と一致する場合:

   • 単一の Datadog サービスが一致する場合、インシデントメトリクスとイベントはサービスとチームと共に発行されます。
   • 複数の Datadog サービスが一致する場合、インシデントメトリクスとイベントはチームと共に発行されます。

   Datadog サービス用の PagerDuty サービス URL の設定に関する詳細は、Software Catalog とのインテグレーションを利用する を参照してください。

3. インシデントの PagerDuty サービス名が Software Catalog 内のサービス名と一致する場合、インシデントメトリクスとイベントはサービスとチームと共に発行されます。

4. インシデントの PagerDuty チーム名が Software Catalog 内のチーム名と一致する場合、インシデントメトリクスとイベントはチームと共に発行されます。

5. インシデントの PagerDuty サービス名が Software Catalog 内のチーム名と一致する場合、インシデントメトリクスとイベントはチームと共に発行されます。

6. ここまでに一致がなかった場合、インシデントメトリクスとイベントはインシデントで提供された PagerDuty サービスと PagerDuty チームと共に発行されます。

独自の障害イベントを送信するには、DORA Metrics API を使用します。障害イベントは、変更障害率と復旧時間を計算するために使用されます。

障害イベントに finished_at 属性を含められると、障害が解決されたことを示します。障害の開始時と解決後にイベントが送信されます。障害イベントは、env、service、および started_at 属性に基づいて照合されます。

要件

• datadog-ci CLI / API が DORA 設定 の Failures イベントデータソースとして有効になっていること。
• 必須の属性は以下のとおりです。
  • services または team (少なくとも 1 つは存在する必要があります)
  • started_at

オプションで以下の属性を障害イベントに追加できます。

• finished_at解決された障害用復旧までの時間を計算するために必要となります
• id 障害の特定用この属性はユーザーが生成するもので、指定しない場合は、Datadog が生成する UUID がエンドポイントによって返されます。
• name障害を説明するために使用します。
• severity
• envDORA Metrics ページ で環境ごとに DORA Metrics をフィルタリングするために使用します。
• repository_url
• commit_sha
• version
• custom_tags: key:value の形式のタグで、DORA Metrics ページ でイベントをフィルタリングするために使用できます。

完全な仕様および追加のコードサンプルについては、DORA Metrics API リファレンスドキュメント をご覧ください。

API (cURL) の例

下記の構成については、<DD_SITE> を以下に置き換えてください :

curl -X POST "https://api.<DD_SITE>/api/v2/dora/failure" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -d @- << EOF
  {
    "data": {
      "attributes": {
        "services": ["shopist"],
        "team": "shopist-devs",
        "started_at": 1693491974000000000,
        "finished_at": 1693491984000000000,
        "git": {
          "commit_sha": "66adc9350f2cc9b250b69abddab733dd55e1a588",
          "repository_url": "https://github.com/organization/example-repository"
        },
        "env": "prod",
        "name": "Web server is down failing all requests",
        "severity": "High",
        "version": "v1.12.07",
        "custom_tags": ["department:engineering", "app_type:backend"]
      }
    }
  }
EOF