Jenkins

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

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

セットアップ

インストール

このプラグインには Jenkins 2.346.1 が必要です。

それ以前のバージョン (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 を利用します。ログの取得設定は Jenkins のロギング文書に記載の手順に従ってください。ロガーの追加画面では、 org.datadog.jenkins.plugins.datadog. で始まるすべての Datadog プラグイン関数と、それに紐付く関数名が自動入力されます。本記事の執筆時点で、利用可能な関数は org.datadog.jenkins.plugins.datadog.listeners.DatadogBuildListener のみとなります。

内容

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

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 ボタンをクリックします。次のオプションを使用できます。

ジョブのカスタマイズ

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

収集データ

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

イベント

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

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

システムイベントタイプ

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

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

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

メトリクス

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`

問題の追跡

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

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

変更

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

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

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

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