This product is not supported for your selected
Datadog site. (
).
概要
DORA Metrics は、デプロイイベントを使用してソフトウェアデリバリーパフォーマンスを追跡および測定します。これらのイベントは、デプロイ頻度、変更リードタイム、変更障害率、復旧時間の 4 つの主要な DORA Metrics を支えています。
DORA Metrics の使用を開始するには、次の手順に従ってください。
Configure a deployment data source: デプロイイベントを Datadog に送信する方法を選択します。APM デプロイ追跡または DORA Metrics API/CLI を介して送信します。
Enrich deployments with commit information: デプロイイベントに Git メタデータ (リポジトリ URL とコミット SHA) を追加します。また、リポジトリを Datadog に同期して、変更リードタイム計算を有効化します。
Customize Change Failure Detection: DORA Metrics は、ロールバック (以前のバージョンを再デプロイする) を通じて失敗したデプロイを自動的に検出し、リバート PR やホットフィックスラベルなどの一般的なロールフォワードパターン用のデフォルトルールを備えています。これらのルールをカスタマイズして、ユーザーのチームの特定のワークフローや修復パターンに合わせることができます。
構成されると、デプロイイベントは、チーム、サービス、環境、および custom tags でフィルタリングされたパフォーマンスデータを、自動的にユーザーの DORA Metrics ダッシュボード に反映します。
制限事項
- データソースオプション (APM デプロイ追跡など) を最初に選択すると、DORA Metrics はその時点からデータを反映し始めます。ソース A からソース B に切り替え、再びソース A に戻ると、ソース A の履歴データは最初に選択された時点以降のもののみ利用可能です。
- 同じサービスに対するデプロイは、同じ秒には発生しません。
DORA Metrics は、デプロイイベントのために以下のデータソースをサポートします。
独自のデプロイイベントを送信するには、DORA Metrics API または datadog-ci dora deployment コマンドを使用します。
要件
- datadog-ci CLI / API は、DORA 設定 において Deployments イベントデータソースとして有効になっていること。
- 必須の属性は以下のとおりです。
started_at: デプロイの開始時刻finished_at: デプロイの終了時刻service: デプロイされたサービス提供されたサービスが、カタログにメタデータがセットアップ (メタデータの追加を参照) されて登録されている場合、サービスの 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 の送信を無効にできます。このオプションが追加されると、変更リードタイムメトリクスは利用できなくなります。
デプロイに関連付けられたサービスが カタログにメタデータがセットアップ (メタデータの追加を参照) されて登録されている場合、サービスの languages と任意の tags が自動的に取得され、イベントに関連付けられます。
変更リードタイムの計算を有効化するには、デプロイのために Git 情報を構成し、リポジトリのメタデータを Datadog と同期させます。こうすることにより、DORA Metrics はコミットが作成されてからデプロイされるまでに要する時間を追跡できます。
Datadog は、デプロイのヘッドコミット SHA の Git 情報 (リポジトリ URL とコミット SHA) へのアクセスを必要とします。要件は、デプロイデータソースによって異なります。
APM デプロイ追跡を通じて特定されたデプロイの場合、トレース形式のアプリケーションテレメトリに Git 情報がタグ付けされていることを確認してください。
注: APM で追跡されたデプロイの場合、変更リードタイムはコミットの作成から新しいバージョンでコミットが最初に観測されるまでの時間として計算されます。Deploy Time メトリクスは利用できません。
DORA Metrics API または datadog-ci dora deployment コマンドで追跡されたデプロイの場合、次のことを確認してください:
- 属性
repository_url と commit_sha が、デプロイイベントのペイロードに含まれています。
Datadog は、あるデプロイとその前のデプロイの間にデプロイされたすべてのコミットを取得するために、リポジトリのメタデータ (コミット、ファイルパス) へのアクセスを必要とします。ユーザーの Git プロバイダーに基づいて同期方法を選択してください。
GitHub インテグレーション がまだインストールされていない場合は、GitHub インテグレーションタイル にインストールしてください。
GitHub アプリケーションの構成時:
- Contents と Pull Requests に対して、少なくとも Read リポジトリ権限を選択してください。
- 少なくとも 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/**
datadog-ci git-metadata upload コマンドを使用して、Git リポジトリのメタデータをアップロードできます。
このコマンドが実行されると、Datadog はリポジトリの URL、現在のブランチのコミット SHA、および追跡したファイルのパスのリストを受け取ります。
新しいコミットごとに CI でこのコマンドを実行してください。特定のコミット SHA に対してデプロイが実行される場合、必ずデプロイイベントが送信される前に、そのコミットに対して datadog-ci git-metadata upload コマンドを実行してください。
コマンドに対して --no-gitsync このオプションを datadog-ci git-metadata upload コマンドに追記します。
そのオプションが含まれている場合、コミット情報は Datadog に送信されず、変更リードタイムメトリックは計算されません。
コマンドの正しいセットアップは、コマンド出力を確認することで検証できます。正しい出力の例を以下に示します。
Reporting commit 007f7f466e035b052415134600ea899693e7bb34 from repository git@github.com:organization/example-repository.git.
180 tracked file paths will be reported.
✅ Handled in 0.077 seconds.
同じリポジトリで複数のサービスを処理する場合
複数のサービスのソースコードが同じリポジトリに存在する場合、デプロイされる特定のサービスに影響するコミットのみを考慮して変更リードタイムが計算されるようにするには、追加の設定が必要です。
サービスに影響を与えるコミットのみを計測するためにフィルタリングするためには、サービス定義 でソースコードの glob ファイルパスパターンを指定します。
サービス定義にアプリケーションフォルダーへの完全な GitHub または GitLab URL が含まれている場合、単一のパスパターンが自動的に使用されます。リンクタイプは repo でなければならず、リンク名は “Source” またはサービスの名前 (以下の例では shopist) でなければなりません。
例 (スキーマバージョン v2.2):
links:
- name: shopist
type: repo
provider: github
url: https://github.com/organization/example-repository/tree/main/src/apps/shopist
links:
- name: shopist
type: repo
provider: gitlab
url: https://gitlab.com/organization/example-repository/-/tree/main/src/apps/shopist?ref_type=heads
links:
- name: shopist
type: repo
provider: azure
url: https://dev.azure.com/organization/project/_git/example-repository?path=/src/apps/shopist
shopist サービスの DORA Metrics は、src/apps/shopist/** 内の変更を含む Git コミットのみを考慮します。extensions[datadoghq.com/dora-metrics] を使用して、より細かくフィルタリングをコントロールできます。例 (スキーマバージョン v2.2):
extensions:
datadoghq.com/dora-metrics:
source_patterns:
- src/apps/shopist/**
- src/libs/utils/**
サービス shopist の DORA Metrics は、src/apps/shopist/** または src/libs/utils/** 内の変更を含む Git コミットのみを考慮します。
サービスに対して 2 つのメタデータエントリーが定義されている場合、コミットをフィルタリングするために考慮されるのは extensions[datadoghq.com/dora-metrics] のみです。
変更障害検出のカスタマイズ
DORA Metrics は、障害が発生したデプロイを自動的に識別して、変更障害率と失敗したデプロイの復旧時間を計算します。
仕組み
変更障害検出 は、修復デプロイを特定し、それを修復中の特定のデプロイにリンクして、すぐに使用できるようにします。
自動検出 (構成不要):
- ロールバック: 以前にデプロイされたバージョンが再デプロイされたときに自動的に検出されます。
カスタムルール (カスタマイズ可能):
- ロールフォワード: リバート PR やホットフィックスラベルのような一般的なパターンに一致するデフォルトルールを通じて検出されます。これらのルールは、DORA 設定 でカスタマイズして、チームの特定のワークフローや修復パターンに合わせることができます。
検出の仕組みやルールのカスタマイズ方法についての詳細情報は、変更障害検出のドキュメント を参照してください。
参考資料