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

Docs > Continuous Integration Visibility > Datadog の CI Pipeline Visibility > GitLab パイプラインでトレースを設定する

互換性

対応する GitLab のバージョン:
GitLab.com (SaaS)
GitLab >= 14.1 (セルフホスティング)
GitLab >= 13.7.0 (セルフホスティング)、機能フラグ datadog_ci_integration を有効にすることで利用可能です
Partial pipelines: 一部再試行とダウンストリームパイプラインの実行を表示する
Manual steps: 手動でトリガーされたパイプラインを表示する
Queue time: パイプラインのジョブが処理されるまでのキューでの待ち時間を表示する
Logs correlation: パイプラインスパンをログに関連付け、ジョブログの収集を有効にする
Infrastructure metric correlation: セルフホスティングの GitLab ランナーのために、パイプラインをインフラストラクチャーホストメトリクスに関連付ける
Custom pre-defined tags: 生成されたすべてのパイプライン、ステージ、ジョブスパンにカスタムタグを構成する
Custom tags and metrics at runtime: ランタイムのカスタムタグとメトリクスを構成する
Parameters: カスタム env または service パラメーターを設定する
Pipeline failure reasons: エラーメッセージからパイプラインの障害理由を特定する

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 Teams と統合する

パイプラインに関連付けられたチームの表示とフィルタリングを行うには、カスタムタグとして team:<your-team> を追加します。カスタムタグ名は、Datadog Teams のチームハンドルと正確に一致している必要があります。

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

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

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

部分的およびダウンストリームパイプライン

Pipeline Executions のページでは、検索バーで以下のフィルターを使用することができます。

Downstream Pipeline: 可能な値: true、false
Manually Triggered: 可能な値: true、false
Partial Pipeline: 可能な値: retry、paused、resumed

検索クエリに Partial Pipeline:retry を入力したパイプラインの実行画面

これらのフィルターは、ページの左側にあるファセットパネルからも適用することができます。

Partial Pipeline ファセットが展開され、値 Retry が選択されたファセットパネル、Partial Retry ファセットが展開され、値 true が選択されたファセットパネル

インフラストラクチャーメトリクスとジョブの相関付け

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

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

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

エラーメッセージは GitLab のバージョン 15.2.0 以降でサポートされています。

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 機能フラグを有効にします。これにより、Pipeline Setup ページの Enable job logs collection チェックボックスが表示されるようになります。
Enable job logs collection をクリックし、Save changes をクリックします。

ジョブログはログ管理で収集され、CI Visibility で GitLab パイプラインと自動的に相関付けられます。1 GiB を超えるログファイルは切り捨てられます。

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

GitLab インテグレーションから収集されたジョブログの処理についての詳細は、プロセッサーのドキュメントを参照してください。