Jenkins プラグインを使用して、Datadog のアカウントにメトリクス、イベント、サービスチェックを自動転送することができます。

注: プラグインの詳細は Jenkins CI プラグインについて も併せてご参照ください。

セットアップ

インストール

このプラグインには Jenkins 2.361.4 と Java 11 が必要です。

それ以前のバージョン (1.632+) の Jenkins をご使用の場合は、こちらからプラグインの 1.2.0 バージョンをご利用ください。

このプラグインはお使いの Jenkins のアップデートセンター (Manage Jenkins -> Manage Plugins) からインストールが可能です。

1. Availableタブを開いて、Datadog を検索し、Datadog Plugin の横のチェックボックスを選択してください。
2. 画面下にある 2 つのインストールボタンのいずれかをクリックすると、プラグインがインストールされます。
3. Installed タブで Datadog Plugin を検索し、プラグインがインストールされたことを確認します。

以下のコンフィギュレーションを続けます。

注: 予期しないバージョンの Datadog Plugin が表示されていた場合は、Manage Jenkins -> Manage Plugins 画面から Check Now を実行してください。

コンフィギュレーション

プラグインから Datadog へのデータ送信については、以下の 2 つの方法で構成することができます。

• Jenkins と Datadog 間で Forwarder として機能する Datadog Agent の使用 (推奨)。
  • 完全な Datadog Agent の代わりに DogStatsD サーバーを使用する場合、メトリクスとイベントのみがサポートされます。
  • 外部ホストから送信されたデータの場合、Datadog Agent は dogstatsd_non_local_traffic: true と apm_non_local_traffic: true のコンフィギュレーションを必要とします。これは、datadog.yaml コンフィギュレーションファイルを使用して構成できます。
• HTTP 経由で Datadog に直接データを送信します。
  • 現在実装されている HTTP クライアントはタイムアウト間隔 1 分でブロッキングを行います。Datadog との接続で問題が発生すると、Jenkins インスタンスにも遅延が起こる可能性があります。

コンフィギュレーションはプラグインのユーザーインターフェースで Groovy スクリプトまたは環境変数を使用して実施可能です。

プラグインのユーザーインターフェース

Datadog のプラグインを構成するには、お使いの Jenkins の Manage Jenkins -> Configure System ページを開いて Datadog Plugin セクションまでスクロールダウンします。

HTTP 転送

1. Use Datadog API URL and Key to report to Datadog (デフォルトで選択されています) の横のラジオボタンを選択します。
2. Jenkins のコンフィギュレーション画面の API Key テキストボックスに Datadog API キーを貼り付けます。Credentails Manager に API キーを保存したい場合は、API キー用の Credential を作成し、Datadog API Key (Select from Credentials) ドロップダウンでその Credential を選択します。
3. Jenkins コンフィギュレーション画面の Test Key ボタンをクリックして、入力した Datadog の API キーをテストします。ボタンは API Key テキストボックスのすぐ下にあります。
4. (オプション) Advanced タブで Jenkins サーバーのホスト名を入力すると、そのサーバーをイベントに含めることができます。
5. (オプション) Datadog ログインテーク URL を入力し、Advanced タブで “Enable Log Collection” を選択します。
6. (オプション) “Enable CI Visibility” を選択し、オプションで CI インスタンス名を構成します。
7. 構成を保存します。

Datadog Agent 転送

1. Use the Datadog Agent to report to Datadog の横のラジオボタンを選択します。
2. Datadog Agent の hostname と port を指定します。
3. (オプション) Advanced タブで Jenkins サーバーのホスト名を入力すると、そのサーバーをイベントに含めることができます。
4. (オプション) ログ収集ポートを入力し、Datadog Agent でログ収集を構成し、“Enable Log Collection” を選択します。
5. (オプション) トレース収集ポートを入力し、“Enable CI Visibility” を選択し、オプションで CI インスタンス名を構成します。
6. 構成を保存します。

Groovy スクリプト

お使いの Datadog プラグインを、以下の Groovy スクリプトを使用して HTTP または DogStatsD 経由でデータ転送するよう構成します。この構成は、Jenkins の公式 Docker イメージまたは plugins.txt と Groovy init スクリプトをサポートするデリバティブを利用して Docker コンテナで Jenkins Master を稼働させている場合に有用です。

Groovy を使用した HTTP 転送

import jenkins.model.*
import org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration

def j = Jenkins.getInstance()
def d = j.getDescriptor("org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration")

// Datadog へのレポートに Datadog API URL とキーを使用する場合
d.setReportWith('HTTP')
d.setTargetApiURL('https://api.datadoghq.com/api/')
d.setTargetApiKey('<DATADOG_API_KEY>')

// カスタムを行う場合は以下の詳細セクションを参照
d.setExcluded('job1,job2')

// ログを収集したい場合
d.setLogIntakeUrl('https://http-intake.logs.datadoghq.com/v1/input/')

// 設定を保存
d.save()

Groovy を使用した Datadog Agent 転送

import jenkins.model.*
import org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration

def j = Jenkins.getInstance()
def d = j.getDescriptor("org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration")

d.setReportWith('DSD')
d.setTargetHost('localhost')
d.setTargetPort(8125)

// ログを収集したい場合
d.setTargetLogCollectionPort(10518)
d.setCollectBuildLogs(true)

// CI Visibility を有効にする場合
d.setTargetTraceCollectionPort(8126)
d.setEnableCiVisibility(true)
d.setCiInstanceName("jenkins")

// カスタムを行う場合は以下の詳細セクションを参照
d.setExcluded('job1,job2')

// コンフィギュレーションを保存
d.save()

環境変数

お使いの Datadog プラグインを、使用するレポートのメカニズムを指定する環境変数 DATADOG_JENKINS_PLUGIN_REPORT_WITH を用いて構成します。

環境変数を使用した HTTP 転送

1. DATADOG_JENKINS_PLUGIN_REPORT_WITH 変数を HTTP に設定します。
2. Datadog の API エンドポイントを指定する DATADOG_JENKINS_PLUGIN_TARGET_API_URL 変数を設定します (デフォルト値は https://api.datadoghq.com/api/) 。
3. Datadog の API キーを指定する DATADOG_JENKINS_PLUGIN_TARGET_API_KEY 変数を設定します。
4. (オプション) ログ収集:

• ログ収集を有効にするには、DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS 変数を true に設定します (デフォルトでは無効になっています)。
• Datadog のログインテーク URL を指定する DATADOG_JENKINS_PLUGIN_TARGET_LOG_INTAKE_URL 変数を設定します (デフォルト値は https://http-intake.logs.datadoghq.com/v1/input/) 。

5. (オプション) CI Visibility (トレース収集):

• CI Visibility を有効にするには、DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY 変数を true に設定します (デフォルトでは無効になっています)。
• Datadog の Webhook インテーク URL を指定する DATADOG_JENKINS_TARGET_WEBHOOK_INTAKE_URL 変数を設定します (デフォルト値は https://webhook-intake.datadoghq.com/api/v2/webhook/) 。
• CI Visibility の Jenkins インスタンスの名前を指定する DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME 変数を設定します (デフォルトは jenkins)。

環境変数を使用した Datadog Agent 転送

1. DATADOG_JENKINS_PLUGIN_REPORT_WITH 変数を DSD に設定します。
2. DogStatsD のサーバーホストを指定する DATADOG_JENKINS_PLUGIN_TARGET_HOST 変数を設定します (デフォルト値は localhost) 。
3. DogStatsD のサーバーポートを指定する DATADOG_JENKINS_PLUGIN_TARGET_PORT 変数を設定します (デフォルト値は 8125)。
4. (オプション) ログ収集:
   • Datadog Agent でログ収集を有効にします。
   • ログ収集を有効にするには、DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS 変数を true に設定します (デフォルトでは無効になっています)。
   • Datadog Agent のログ収集用ポートを指定する DATADOG_JENKINS_PLUGIN_TARGET_LOG_COLLECTION_PORT を設定します。
5. (オプション) CI Visibility (トレース収集):
   • CI Visibility を有効にするには、DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY 変数を true に設定します (デフォルトでは無効になっています)。
   • Datadog Agent トレース収集ポート (デフォルトは 8126) を指定する DATADOG_JENKINS_PLUGIN_TARGET_TRACE_COLLECTION_PORT 変数を設定します。
   • CI Visibility の Jenkins インスタンスの名前を指定する DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME 変数を設定します (デフォルトは jenkins)。

さらに、標準の Datadog 環境変数を使用できます。

• Datadog Agent ホストを指定する DD_AGENT_HOST 変数を設定します。
• DogStatsD サーバーポートを指定する DD_AGENT_PORT 変数を設定します。
• Datadog Agent トレース収集ポートを指定する DD_TRACE_AGENT_PORT 変数を設定します。
• トレースを送信する Datadog Agent URL を指定する DD_TRACE_AGENT_URL 変数を設定します。設定すると、これは DD_AGENT_HOST および DD_TRACE_AGENT_PORT よりも優先されます。

DATADOG_JENKINS_PLUGIN ネームスペースを持つ環境変数は、標準の Datadog 環境変数よりも優先されます。

ロギング

ロギングは、Jenkins のベストプラクティスに従う java.util.Logger を利用して行われます。

「Datadog Plugin Logs」というカスタムロガーが自動的に登録され、このロガーはプラグインのログをレベル INFO 以上で記録します。 カスタムロガーの登録は、環境変数 DD_JENKINS_PLUGIN_LOG_RECORDER_ENABLED を false に設定することで無効化できます。 プラグインのログを最大限詳細に確認したい場合は、カスタムロガーのレベルを手動で ALL に変更してください。

カスタマイズ

パイプラインのカスタマイズ

Datadog プラグインは、パイプラインベースのジョブの構成オプションを提供する datadog ステップを追加します。

宣言的パイプラインでは、トップレベルの options ブロックに、次のようにステップを追加します。

pipeline {
    agent any
    options {
        datadog(collectLogs: true, tags: ["foo:bar", "bar:baz"])
    }
    stages {
        stage('Example') {
            steps {
                echo "Hello world."
            }
        }
    }
}

スクリプト化されたパイプラインでは、関連セクションを Datadog ステップでラップします。

datadog(collectLogs: true, tags: ["foo:bar", "bar:baz"]) {
  node {
    stage('Example') {
      echo "Hello world."
    }
  }
}

注: パイプラインのカスタマイズは、ジョブの開始後にのみ登録されます。パイプラインのカスタマイズで指定されたタグは、jenkins.job.started に関連付けられません。

グローバルカスタマイズ

グローバルコンフィギュレーションをカスタマイズするには、Jenkins で Manage Jenkins -> Configure System に移動し、Advanced ボタンをクリックします。次のオプションを使用できます。

ジョブのカスタマイズ

各ジョブのコンフィギュレーションページでは、次のようなカスタマイズが可能です。

Test Visibility 構成

このプラグインは、ジョブやパイプラインに対して Datadog の Test Visibility を自動的に構成することができます (使用しているテストフレームワークがサポートされているか確認するために、ご使用言語の Test Visibility のドキュメントを参照してください。また、コンテナ内で実行されるテストには自動構成がサポートされていないことに注意してください。コンテナ化されたテスト実行に Test Visibility を有効にするためには、手動インスツルメンテーションの手順に従ってください)。

Test Visibility を有効にする前に、Datadog にデータを送信するようにプラグインを適切に構成してください。

Test Visibility の自動構成を有効にするには、2 つのオプションがあります。

1. Jenkins UI を使用する (プラグイン v5.6.0 以降で使用可能): テストをトレースする必要があるジョブまたはパイプラインの Configure ページに移動し、General セクションの Enable Datadog Test Visibility チェックボックスにチェックを入れ、変更を保存します。このオプションは、Multibranch Pipelines、Organization Folders、または全体的に Jenkinsfile で構成されたその他のタイプのパイプラインを使用している場合は使用できません。
2. datadog パイプラインステップを使用する (プラグイン v5.6.2 以降で使用可能):

宣言的パイプラインでは、トップレベルの options ブロックに、次のようにステップを追加します。

pipeline {
    agent any
    options {
        datadog(testVisibility: [ 
            enabled: true, 
            serviceName: "my-service", // the name of service or library being tested
            languages: ["JAVA"], // languages that should be instrumented (available options are "JAVA", "JAVASCRIPT", "PYTHON", "DOTNET")
            additionalVariables: ["my-var": "value"]  // additional tracer configuration settings (optional)
        ])
    }
    stages {
        stage('Example') {
            steps {
                echo "Hello world."
            }
        }
    }
}

スクリプト化されたパイプラインでは、関連セクションを datadog ステップでラップします。

datadog(testVisibility: [ enabled: true, serviceName: "my-service", languages: ["JAVA"], additionalVariables: [:] ]) {
  node {
    stage('Example') {
      echo "Hello world."
    }
  }
}

collectLogs や tags などの他の datadog の設定は testVisibility ブロックと一緒に追加することができます。

Test Visibility は、Datadog の別製品であり、別途請求されることにご留意ください。

データ収集

このプラグインは以下のイベント、メトリクス、サービスチェックを収集します。

イベント

デフォルトのイベントタイプ

注: event_type は上記のイベントとメトリクスに対して常に default に設定されます。

システムイベントタイプ

注: event_type は上記のイベントとメトリクスに対して常に system に設定されます。

セキュリティイベントタイプ

注: event_type は上記のイベントとメトリクスに対して常に security に設定されます。

イベントの絞り込み

このプラグインを使用すれば、上記の特定のイベント名だけでなく、イベントタイプによってイベントをフィルタリングすることができます。システムまたはセキュリティタイプのすべてのイベントを含める/除外するには

• UI で: これらのイベントのチェックボックスをオフにします。
• groovy スクリプトで: Datadog グローバル記述子を取得し、d.setEmitSystemEvents() または d.setEmitSecurityEvents() を呼び出します。
• 環境変数セクションで: セキュリティイベントやシステムイベントを発生させるための環境変数を設定します。

送信されるイベントをより詳細に制御するために、3 つの構成オプションが提供され、イベント名の文字列のカンマで区切られた含有/除外リストを許可します。含有/除外はイベントタイプによるフィルタリングよりも優先されます。例えば、security イベントはオフに切り替えることができますが、UserAuthenticated を含めることが優先されるため、security タイプからは UserAuthenticated イベントのみが送信されます。UI では、含有リストと除外リストの両方にテキストボックスが用意されています。groovy スクリプトでは、d.setIncludeEvents() メソッドと d.setExcludeEvents() メソッドがカンマで区切られたイベント名のリストを入力として受け付け、これはもう一つの有効な構成メソッドです。ます。最後に、環境変数が用意されており、手動で含有/除外リストを設定することができます。

注: ジョブのカスタマイズセクションで言及されているように、SCMCheckout イベントを送信するためのジョブ固有のトグルがあります。SCMCheckout イベントがグローバルに除外されている場合、このトグルは無効です。

メトリクス

Agent のログ収集

注: このコンフィギュレーションは、Datadog Agent コンフィギュレーションを使用するものにのみ適用されます。

1. Datadog Agent で、ログの収集はデフォルトで無効になっています。以下のように、datadog.yaml ファイルでこれを有効にします。

   logs_enabled: true
   

2. Jenkins ログを収集するには、次のように conf.d/jenkins.d 内に conf.yaml を作成して、Agent のカスタムログソースファイルを作成します。

   logs:
     - type: tcp
       port: <PORT>
       service: <SERVICE>
       source: jenkins
   

3. Jenkins では、上記で指定したポートを Log Collection Port として登録します。環境変数、Groovy スクリプト、Jenkins UI で設定することが可能です。

4. Agent を再起動します。

サービスチェック

ビルドステータス jenkins.job.status にデフォルトタグを適用: jenkins_url、job、node、user_id`

トラブルシューティング

診断用フレアの生成。

プラグイン診断フレアには、プラグインの問題を診断するために使用できるデータが含まれています。 本稿執筆時点では、フレアには以下の内容が含まれています。

• XML 形式のプラグイン構成
• プラグイン接続チェックの結果
• 実行時データ (JVM、Jenkins Core、プラグインの現在のバージョン)
• プラグインコード内で発生した最近の例外
• レベル INFO 以上のプラグインログ、および最近の Jenkins コントローラログ
• Jenkins コントローラプロセスの現在のスレッドスタック
• 環境変数で、DD_ または DATADOG_ で始まるもの (API キーおよび/またはアプリキーを除く)

フレアを生成するには、Manage Jenkins ページに移動し、Troubleshooting セクションを見つけ、Datadog を選択します。 Download Diagnostic Flare をクリックして (「MANAGE」権限が必要です)、フレアを生成します。

問題の追跡

このプラグイン jenkinsci/datadog-plugin/issuesに関する問題はすべて、GitHub に搭載の問題追跡システムを使用して追跡を行います。 しかし、Jenkins プラグインのホスティング状況に応じて、JIRA に課題が作成される場合があります。関連する課題の投稿については、 Jenkins の課題ページをご参照ください。

注: Datadog に関連する JIRA の課題で未解決のものが存在します。

変更

CHANGELOG.md をご参照ください。

コードへのコントリビューション

開発に対するアイデアを共有いただけることに、まずは深く感謝を申し上げます。

課題やプルリクエストの送信前に、ドキュメント寄稿ガイドラインをお読みください。 開発用ドキュメントでも、ローカル開発環境の準備などに関するヒントをご紹介しています。