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

選択したサイト () では、現時点では CI Visibility は使用できません。

互換性

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

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

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

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

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

プロジェクトまたはグループでのインテグレーションを構成するには、インスツルメントしたい各プロジェクトまたはグループに対して Settings > Integrations > 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 eventsPipeline 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 からのエラータイプに関連するメッセージを表示します。

GitLab の失敗の理由

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

エラーの種類エラーメッセージエラードメイン
unknown_failure原因不明で失敗不明
config_errorCI/CD コンフィギュレーションファイルのエラーによる失敗ユーザー
external_validation_failure外部パイプラインの検証のため失敗不明
user_not_verifiedユーザーが認証されていないため、パイプラインが失敗したユーザー
activity_limit_exceededパイプラインのアクティビティ制限を超過したプロバイダー
size_limit_exceededパイプラインのサイズ制限を超過したプロバイダー
job_activity_limit_exceededパイプラインのジョブアクティビティ制限を超過したプロバイダー
deployments_limit_exceededパイプラインのデプロイ制限を超過したプロバイダー
project_deletedこのパイプラインに関連するプロジェクトが削除されたプロバイダー
api_failureAPI の失敗プロバイダー
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_exceededCI の割り当て超過プロバイダー
pipeline_loop_detectedパイプラインループを検出ユーザー
builds_disabledビルド無効ユーザー
deployment_rejectedデプロイメントが拒否されたユーザー
protected_environment_failure環境に関する失敗プロバイダー
secrets_provider_not_foundシークレットプロバイダーが見つからないユーザー
reached_max_descendant_pipelines_depth子孫パイプラインの最大値に到達ユーザー
ip_restriction_failureIP 制限の失敗プロバイダー

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

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

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

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

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

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

その他の参考資料