Jenkins

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

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: trueapm_non_local_traffic: true のコンフィギュレーションを必要とします。これは、datadog.yaml コンフィギュレーションファイルを使用して構成できます。
  • HTTP 経由で Datadog に直接データを送信します。
    • 現在実装されている HTTP クライアントはタイムアウト間隔 1 分でブロッキングを行います。Datadog との接続で問題が発生すると、Jenkins インスタンスにも遅延が起こる可能性があります。
    • この方法は現在、“CI Visibility” 製品で使用されるトレース収集をサポートしていません。

コンフィギュレーションはプラグインのユーザーインターフェース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. 構成を保存します。
Datadog Agent 転送
  1. Use the Datadog Agent to report to Datadog の横のラジオボタンを選択します。
  2. Datadog Agent の hostnameport を指定します。
  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 のログインテーク URL を指定する DATADOG_JENKINS_PLUGIN_TARGET_LOG_INTAKE_URL 変数を設定します (デフォルト値は https://http-intake.logs.datadoghq.com/v1/input/) 。
環境変数を使用した 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 Agent のログ収集用ポートを指定する DATADOG_JENKINS_PLUGIN_TARGET_LOG_COLLECTION_PORT を設定します。
    • ログ収集を有効にするには、DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS 変数を true に設定します (デフォルトでは無効になっています)。
  5. (オプション) CI Visibility (トレース収集):
    • Datadog Agent トレース収集ポート (デフォルトは 8126) を指定する DATADOG_JENKINS_PLUGIN_TARGET_TRACE_COLLECTION_PORT 変数を設定します。
    • CI Visibility を有効にするには、DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY 変数を true に設定します (デフォルトでは無効になっています)。
    • 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” のステップが追加され、パイプラインベースのジョブに対するコンフィギュレーションオプションが提供されます。 宣言型パイプラインでは、トップレベルのオプションブロックにステップを追加します。

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

内容説明環境変数
ホスト名Datadog に送信されるすべてのイベントで使用するホスト名。DATADOG_JENKINS_PLUGIN_HOSTNAME
除外されるジョブ監視対象から除外したいジョブ名を指定する正規表現を記載したカンマ区切りリストです。例: susans-job,johns-.*,prod_folder/prod_releaseDATADOG_JENKINS_PLUGIN_EXCLUDED
含まれるジョブ監視対象に含めたいジョブ名を指定する正規表現を記載したカンマ区切りリストです。例: susans-job,johns-.*,prod_folder/prod_releaseDATADOG_JENKINS_PLUGIN_INCLUDED
グローバルタグファイルタグのカンマ区切りリストを含むワークスペースファイルへのパスです (パイプラインのジョブとは互換不能) 。DATADOG_JENKINS_PLUGIN_GLOBAL_TAG_FILE
グローバルタグすべてのメトリクス、イベント、サービスチェックを適用するためのカンマ区切りのリストです。タグにはマスターの jenkins インスタンスで定義される環境変数を含めることができます。 DATADOG_JENKINS_PLUGIN_GLOBAL_TAGS
グローバルジョブタグジョブとそのジョブに適用するタグのリストを照合するための正規表現を記載したカンマ区切りリストです。タグにはマスターの jenkins インスタンスで定義される環境変数を含めることができます。: タグで $ 記号を用いて正規表現に一致したグループを参照することができます。例: (.*?)_job_(*?)_release, owner:$1, release_env:$2, optional:Tag3DATADOG_JENKINS_PLUGIN_GLOBAL_JOB_TAGS
セキュリティ監査イベントの送信イベントおよびメトリクスの Security Events Type を送信します (デフォルトで有効) 。DATADOG_JENKINS_PLUGIN_EMIT_SECURITY_EVENTS
システムイベントの送信イベントおよびメトリクスの System Events Type を送信します (デフォルトで有効) 。DATADOG_JENKINS_PLUGIN_EMIT_SYSTEM_EVENTS

ジョブのカスタマイズ

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

内容説明
カスタムタグジョブワークスペースの File から設定 (パイプラインのジョブではサポートされていません) するか、コンフィギュレーションページのテキスト Properties から直接設定します。設定が完了すると、この内容で Global Job Tags が上書きされます。
ソース管理のイベントを送信イベントおよびメトリクスの Source Control Management Events Type を送信します (デフォルトで有効) 。

収集データ

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

イベント

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

イベント名トリガーデフォルトのタグ関連するレートメトリクス
ビルド開始RunListener#onStartedbranch, event_type, jenkins_url, job, node, user_idjenkins.job.started
ビルド中止RunListener#onDeletedbranch, event_type, jenkins_url, job, node, user_idjenkins.job.aborted
ビルド完了RunListener#onCompletedbranch, event_type, jenkins_url, job, node, result, user_idjenkins.job.completed
SCM チェックアウトSCMListener#onCheckoutbranch, event_type, jenkins_url, job, node, user_idjenkins.scm.checkout

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

システムイベントタイプ

イベント名トリガーデフォルトのタグ関連するレートメトリクス
コンピューターのオンラインComputerListener#onOnlineevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.online
コンピューターのオフラインComputerListener#onOfflineevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.offline
コンピューターの一時オンラインComputerListener#onTemporarilyOnlineevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.temporarily_online
コンピューターの一時オフラインComputerListener#onTemporarilyOfflineevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.temporarily_offline
コンピューターの起動失敗ComputerListener#onLaunchFailureevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.launch_failure
アイテムの作成ItemListener#onCreatedevent_type, jenkins_url, user_idjenkins.item.created
アイテムの削除ItemListener#onDeletedevent_type, jenkins_url, user_idjenkins.item.deleted
アイテムの更新ItemListener#onUpdatedevent_type, jenkins_url, user_idjenkins.item.updated
アイテムのコピーItemListener#onCopiedevent_type, jenkins_url, user_idjenkins.item.copied
アイテムの場所変更ItemListener#onLocationChangedevent_type, jenkins_url, user_idjenkins.item.location_changed
構成の変更SaveableListener#onChangeevent_type, jenkins_url, user_idjenkins.config.changed

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

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

イベント名トリガーデフォルトのタグ関連するレートメトリクス
ユーザー認証成功SecurityListener#authenticatedevent_type, jenkins_url, user_idjenkins.user.authenticated
ユーザー認証失敗SecurityListener#failedToAuthenticateevent_type, jenkins_url, user_idjenkins.user.access_denied
ユーザーのログアウトSecurityListener#loggedOutevent_type, jenkins_url, user_idjenkins.user.logout

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

メトリクス

メトリクス名説明デフォルトのタグ
jenkins.computer.launch_failureコンピューターの起動失敗レートjenkins_url
jenkins.computer.offlineコンピューターのオフラインレートjenkins_url
jenkins.computer.onlineコンピューターのオンラインレートjenkins_url
jenkins.computer.temporarily_offlineコンピューターの一時的なオフラインレートjenkins_url
jenkins.computer.temporarily_onlineコンピューターの一時的なオンラインレートjenkins_url
jenkins.config.changed変更された構成レートjenkins_url, user_id
jenkins.executor.countエグゼキューター総数jenkins_url, node_hostname, node_name, node_label
jenkins.executor.free使用されていないエグゼキューター数jenkins_url, node_hostname, node_name, node_label
jenkins.executor.in_useアイドル状態のエグゼキューター数jenkins_url, node_hostname, node_name, node_label
jenkins.item.copiedアイテムのコピーレートjenkins_url, user_id
jenkins.item.createdアイテムの作成レートjenkins_url, user_id
jenkins.item.deletedアイテムの削除レートjenkins_url, user_id
jenkins.item.location_changedアイテムの移動レートjenkins_url, user_id
jenkins.item.updatedアイテムの更新レートjenkins_url, user_id
jenkins.job.abortedジョブの中止レートbranch, jenkins_url, job, node, user_id
jenkins.job.build_duration一時停止なしのビルドの所要時間 (秒単位)。branch, jenkins_url, job, node, result, user_id
jenkins.job.completedジョブの完了レートbranch, jenkins_url, job, node, result, user_id
jenkins.job.cycletimeビルドのサイクル時間branch, jenkins_url, job, node, result, user_id
jenkins.job.durationビルドの所要時間 (秒単位)branch, jenkins_url, job, node, result, user_id
jenkins.job.feedbacktimeコードのコミットからジョブの失敗までのフィードバック時間branch, jenkins_url, job, node, result, user_id
jenkins.job.leadtimeビルドのリードタイムbranch, jenkins_url, job, node, result, user_id
jenkins.job.mtbfMTBF: 最後に成功したジョブから現在失敗したジョブまでの時間branch, jenkins_url, job, node, result, user_id
jenkins.job.mttrMTTR: 最後に失敗したジョブから現在成功したジョブまでの時間branch, jenkins_url, job, node, result, user_id
jenkins.job.pause_durationビルドジョブの一時停止期間 (秒単位)。branch, jenkins_url, job, node, result, user_id
jenkins.job.startedジョブの開始レートbranch, jenkins_url, job, node, user_id
jenkins.job.stage_duration個々のステージの期間。jenkins_urljobuser_idstage_namestage_depthstage_parentresult
jenkins.job.stage_pause_duration個々のステージの一時停止期間(ミリ秒)。jenkins_urljobuser_idstage_namestage_depthstage_parentresult
jenkins.job.stage_completedステージの完了レートjenkins_urljobuser_idstage_namestage_depthstage_parentresult
jenkins.job.waitingジョブ実行までの待ち時間 (ミリ秒単位)branch, jenkins_url, job, node, user_id
jenkins.node.countノード総数jenkins_url
jenkins.node.offlineオフラインのノード数jenkins_url
jenkins.node.onlineオンラインのノード数jenkins_url
jenkins.node_status.countこのノードが存在する場合。jenkins_url, node_hostname, node_name, node_label
jenkins.node_status.up特定のノードがオンラインの場合、値は 1。それ以外の場合は 0。jenkins_url, node_hostname, node_name, node_label
jenkins.plugin.countプラグイン総数jenkins_url
jenkins.plugin.activeプラグインは有効です。jenkins_url
jenkins.plugin.failedプラグインに失敗しました。jenkins_url
jenkins.plugin.inactivateプラグインは無効です。jenkins_url
jenkins.plugin.withUpdateプラグインに更新があります。jenkins_url
jenkins.project.countプロジェクト総数jenkins_url
jenkins.queue.sizeキューサイズjenkins_url
jenkins.queue.buildableキュー内のビルド可能なアイテム数jenkins_url
jenkins.queue.pendingキュー内の保留アイテム数jenkins_url
jenkins.queue.stuckキュー内の立ち往生 (スタック) アイテム数jenkins_url
jenkins.queue.blockedキュー内のブロックされたアイテム数jenkins_url
jenkins.queue.job.in_queueジョブがキューに入れられた回数。jenkins_urljob_name
jenkins.queue.job.buildableジョブがキューでビルド可能になった回数。jenkins_urljob_name
jenkins.queue.job.pendingジョブがキューで保留された回数。jenkins_urljob_name
jenkins.queue.job.stuckジョブがキューでスタックした回数。jenkins_urljob_name
jenkins.queue.job.blockedジョブがキューでブロックされた回数。jenkins_urljob_name
jenkins.scm.checkoutSCM チェックアウトのレートbranch, jenkins_url, job, node, user_id
jenkins.user.access_denied認証に失敗したユーザーレートjenkins_url, user_id
jenkins.user.authenticated認証したユーザーレートjenkins_url, user_id
jenkins.user.logoutログアウトしたユーザーレートjenkins_url, user_id

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、jobnodeuser_id`

問題の追跡

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

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

変更

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

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

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

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