GitLab パイプラインでトレースを設定する

互換性

対応する GitLab のバージョン:

GitLab.com (SaaS)
GitLab >= 14.1 (セルフホスティング)

その他の対応バージョン (追加構成あり):

GitLab >= 13.7.0 (セルフホスティング)、機能フラグ datadog_ci_integration を有効にすることで利用可能です。

Datadog インテグレーションの構成

プロジェクトまたはグループでのインテグレーションを構成するには、インスツルメントしたい各プロジェクトまたはグループに対して Settings > Integrations > Datadog に移動します。

また、GitLab インスタンスレベルで、Admin > Settings > Integrations > Datadog にアクセスして、インテグレーションを有効にすることができます。

datadog_ci_integration 機能フラグを有効にして、インテグレーションを有効にします。インストールの種類に応じて、GitLab の Rails Runner を使用する次のコマンドのいずれかを実行します。

Omnibus インストール

sudo gitlab-rails runner "Feature.enable(:datadog_ci_integration)"

ソースインストールから

sudo -u git -H bundle exec rails runner \
  -e production \
  "Feature.enable(:datadog_ci_integration)"

Kubernetes インストール

kubectl exec -it <task-runner-pod-name> -- \
  /srv/gitlab/bin/rails runner "Feature.enable(:datadog_ci_integration)"

次に、インスツルメントしたい各プロジェクトの Settings > Integrations > Datadog で、プロジェクト単位でインテグレーションを構成します。

注: GitLab の初期バージョンのバグにより、GitLab のバージョン 14.1 未満では、GitLab の UI でオプションが利用可能であっても、グループまたはインスタンスレベルで Datadog インテグレーションを有効にすることができません。

インテグレーションコンフィギュレーション設定を入力します。

Active: インテグレーションを有効にします。
Datadog site: データを送信する Datadog サイトを指定します。
デフォルト: datadoghq.com
選択したサイト:
API URL (オプション): データを直接送信するために使用される API URL をオーバーライドできます。これは、高度なシナリオでのみ使用されます。
デフォルト: (空、オーバーライドなし)
API key: データを送信するときに使用する API キーを指定します。Datadog の Integrations セクションの APIs タブで生成できます。
Service (オプション): インテグレーションによって生成された各スパンにアタッチするサービス名を指定します。これを使用して、GitLab インスタンスを区別します。
デフォルト: gitlab-ci
Env (オプション): インテグレーションによって生成された各スパンに接続する環境 (env タグ) を指定します。これを使用して、GitLab インスタンスのグループを区別します (例: ステージングまたは本番)。
デフォルト: none
タグ (オプション): インテグレーションによって生成された各スパンに付ける任意のカスタムタグを指定します。1 行に 1 つのタグを key:value の形式で指定します。
デフォルト: (空、追加タグなし)
注: GitLab.com と GitLab >= 14.8 セルフホスティングでのみ利用可能です。

Test settings ボタンを使用してインテグレーションをテストできます (プロジェクトでインテグレーションを構成する場合にのみ使用できます)。成功したら、Save changes をクリックしてインテグレーションのセットアップを完了します。

Webhook を介したインテグレーション

ネイティブの Datadog インテグレーションを使用する代わりに、Webhook を使用してパイプラインデータを Datadog に送信できます。

注: ネイティブの Datadog インテグレーションは、推奨されるアプローチであり、積極的に開発中のオプションです。

リポジトリ (または GitLab インスタンス設定) の Settings > Webhooks に移動し、新しい Webhook を追加します。

URL: https://webhook-intake./api/v2/webhook/?dd-api-key=<API_KEY> ここで、<API_KEY> は Datadog API キーです。
Secret Token: 空白のままにします
Trigger: Job events と Pipeline events を選択します。

カスタムの env または service パラメーターを設定するには、Webhook の URL で他のクエリパラメーターを追加します: &env=<YOUR_ENV>&service=<YOUR_SERVICE_NAME>

カスタムタグの設定

インテグレーションによって生成されたすべてのパイプラインとジョブのスパンにカスタムタグを設定するには、URL に URL エンコードされたクエリパラメーター tags を追加し、key:value ペアをカンマで区切って指定します。key:value のペアにカンマが含まれる場合は、引用符で囲んでください。例えば、key1:value1, "key2: value with , comma",key3:value3 を追加するには、以下の文字列を Webhook URL に追記する必要があります。

?tags=key1%3Avalue1%2C%22key2%3A+value+with+%2C+comma%22%2Ckey3%3Avalue3

Datadog でパイプラインデータを視覚化する

インテグレーションが正常に構成されたら、パイプラインが終了した後、Pipelines ページと Pipeline Executions ページにデータが入力されます。

注: Pipelines ページには、各リポジトリのデフォルトブランチのデータのみが表示されます。

インフラストラクチャーメトリクスの相関

セルフホスティングの GitLab ランナーを使っている場合、ジョブとそれを実行しているインフラストラクチャーを関連付けることができます。この機能を使うには、GitLab ランナーに host:<hostname> という形式のタグが必要です。タグは、新しいランナーを登録する際に追加することができます。既存のランナーでは、ランナーの config.toml を更新することでタグを追加します。または、UI から Settings > CI/CD > Runners に移動して、該当するランナーを編集することでタグを追加します。

これらのステップの後、CI Visibility は各ジョブにホスト名を追加します。メトリクスを見るには、トレースビューでジョブスパンをクリックします。ドロワーに、ホストメトリクスを含む Infrastructure という新しいタブが表示されます。

パイプライン失敗時のエラーメッセージ

GitLab パイプラインの実行に失敗した場合、特定のパイプライン実行内の Errors タブの下の各エラーは、GitLab からのエラータイプに関連するメッセージを表示します。

各エラータイプに関連するメッセージとドメインについては、以下の表を参照してください。リストにないエラータイプは、Job failed というエラーメッセージと unknown というエラードメインになります。

エラーの種類	エラーメッセージ	エラードメイン
unknown_failure	原因不明で失敗	不明
config_error	CI/CD コンフィギュレーションファイルのエラーによる失敗	ユーザー
external_validation_failure	外部パイプラインの検証のため失敗	不明
user_not_verified	ユーザーが認証されていないため、パイプラインが失敗した	ユーザー
activity_limit_exceeded	パイプラインのアクティビティ制限を超過した	プロバイダー
size_limit_exceeded	パイプラインのサイズ制限を超過した	プロバイダー
job_activity_limit_exceeded	パイプラインのジョブアクティビティ制限を超過した	プロバイダー
deployments_limit_exceeded	パイプラインのデプロイ制限を超過した	プロバイダー
project_deleted	このパイプラインに関連するプロジェクトが削除された	プロバイダー
api_failure	API の失敗	プロバイダー
stuck_or_timeout_failure	パイプラインが停止している、またはタイムアウトしている	不明
runner_system_failure	ランナーシステムの不具合による失敗	プロバイダー
missing_dependency_failure	依存関係がないため失敗	不明
runner_unsupported	未対応のランナーのため失敗	プロバイダー
stale_schedule	スケジュールが古くなったため失敗	プロバイダー
job_execution_timeout	ジョブのタイムアウトによる失敗	不明
archived_failure	アーカイブの失敗	プロバイダー
unmet_prerequisites	前提条件が満たされていないため失敗	不明
scheduler_failure	スケジュール不具合による失敗	プロバイダー
data_integrity_failure	データ整合性のため失敗	プロバイダー
forward_deployment_failure	デプロイメントの失敗	不明
user_blocked	ユーザーによってブロックされた	ユーザー
ci_quota_exceeded	CI の割り当て超過	プロバイダー
pipeline_loop_detected	パイプラインループを検出	ユーザー
builds_disabled	ビルド無効	ユーザー
deployment_rejected	デプロイメントが拒否された	ユーザー
protected_environment_failure	環境に関する失敗	プロバイダー
secrets_provider_not_found	シークレットプロバイダーが見つからない	ユーザー
reached_max_descendant_pipelines_depth	子孫パイプラインの最大値に到達	ユーザー
ip_restriction_failure	IP 制限の失敗	プロバイダー

ジョブログ収集を有効にする (ベータ版)

以下の GitLab バージョンは、ジョブログの収集をサポートしています。

GitLab.com (SaaS)
GitLab >= 14.8 (セルフホスティング) ジョブログを格納するオブジェクトストレージを使用している場合のみ

ジョブログの収集を有効にするには

GitLab セルフホストまたは GitLab.com アカウントで datadog_integration_logs_collection 機能フラグを有効化します。これにより、Datadog インテグレーションにある Enable logs collection オプションが表示されます。
Enable logs collection オプションを有効にし、変更を保存します。

ジョブログは Logs 製品に収集され、CI Visibility 内で GitLab パイプラインと自動的に相関が取られます。

注: Logs は、CI Visibility とは別課金となります。