- 重要な情報
- はじめに
- 用語集
- ガイド
- エージェント
- インテグレーション
- OpenTelemetry
- 開発者
- API
- CoScreen
- アプリ内
- Service Management
- インフラストラクチャー
- アプリケーションパフォーマンス
- 継続的インテグレーション
- ログ管理
- セキュリティ
- UX モニタリング
- 管理
Jenkins プラグインを使用して、Datadog のアカウントにメトリクス、イベント、サービスチェックを自動転送することができます。
注: プラグインの詳細は Jenkins CI プラグインについて も併せてご参照ください。
このプラグインには Jenkins 2.346.1 が必要です。
それ以前のバージョン (1.632+) の Jenkins をご使用の場合は、こちらからプラグインの 1.2.0 バージョンをご利用ください。
このプラグインはお使いの Jenkins のアップデートセンター (Manage Jenkins -> Manage Plugins
) からインストールが可能です。
Available
タブを開いて、Datadog
を検索し、Datadog Plugin
の横のチェックボックスを選択してください。Installed
タブで Datadog Plugin
を検索し、プラグインがインストールされたことを確認します。以下のコンフィギュレーションを続けます。
注: 予期しないバージョンの Datadog Plugin
が表示されていた場合は、Manage Jenkins -> Manage Plugins
画面から Check Now
を実行してください。
プラグインから Datadog へのデータ送信については、以下の 2 つの方法で構成することができます。
dogstatsd_non_local_traffic: true
と apm_non_local_traffic: true
のコンフィギュレーションを必要とします。これは、datadog.yaml
コンフィギュレーションファイルを使用して構成できます。コンフィギュレーションはプラグインのユーザーインターフェースで Groovy スクリプトまたは環境変数を使用して実施可能です。
Datadog のプラグインを構成するには、お使いの Jenkins の Manage Jenkins -> Configure System
ページを開いて Datadog Plugin
セクションまでスクロールダウンします。
API Key
テキストボックスに Datadog API キーを貼り付けます。Credentails Manager に API キーを保存したい場合は、API キー用の Credential を作成し、Datadog API Key (Select from Credentials)
ドロップダウンでその Credential を選択します。Test Key
ボタンをクリックして、入力した Datadog の API キーをテストします。ボタンは API Key テキストボックスのすぐ下にあります。hostname
と port
を指定します。お使いの Datadog プラグインを、以下の Groovy スクリプトを使用して HTTP または DogStatsD 経由でデータ転送するよう構成します。この構成は、Jenkins の公式 Docker イメージまたは plugins.txt
と Groovy init スクリプトをサポートするデリバティブを利用して Docker コンテナで Jenkins Master を稼働させている場合に有用です。
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()
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
を用いて構成します。
DATADOG_JENKINS_PLUGIN_REPORT_WITH
変数を HTTP
に設定します。DATADOG_JENKINS_PLUGIN_TARGET_API_URL
変数を設定します (デフォルト値は https://api.datadoghq.com/api/
) 。DATADOG_JENKINS_PLUGIN_TARGET_API_KEY
変数を設定します。DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS
変数を true
に設定します (デフォルトでは無効になっています)。DATADOG_JENKINS_PLUGIN_TARGET_LOG_INTAKE_URL
変数を設定します (デフォルト値は https://http-intake.logs.datadoghq.com/v1/input/
) 。DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY
変数を true
に設定します (デフォルトでは無効になっています)。DATADOG_JENKINS_TARGET_WEBHOOK_INTAKE_URL
変数を設定します (デフォルト値は https://webhook-intake.datadoghq.com/api/v2/webhook/
) 。DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME
変数を設定します (デフォルトは jenkins
)。DATADOG_JENKINS_PLUGIN_REPORT_WITH
変数を DSD
に設定します。DATADOG_JENKINS_PLUGIN_TARGET_HOST
変数を設定します (デフォルト値は localhost
) 。DATADOG_JENKINS_PLUGIN_TARGET_PORT
変数を設定します (デフォルト値は 8125
)。DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS
変数を true
に設定します (デフォルトでは無効になっています)。DATADOG_JENKINS_PLUGIN_TARGET_LOG_COLLECTION_PORT
を設定します。DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY
変数を true
に設定します (デフォルトでは無効になっています)。8126
) を指定する DATADOG_JENKINS_PLUGIN_TARGET_TRACE_COLLECTION_PORT
変数を設定します。DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME
変数を設定します (デフォルトは jenkins
)。さらに、標準の Datadog 環境変数を使用できます。
DD_AGENT_HOST
変数を設定します。DD_AGENT_PORT
変数を設定します。DD_TRACE_AGENT_PORT
変数を設定します。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
ステップを追加します。
オプション (タイプ) | 説明 |
---|---|
collectLogs (boolean ) | ログ収集がグローバルで無効になっている場合、パイプラインで有効にします。 |
tags (String[] ) | パイプラインについて収集されたすべてのデータにアタッチするタグのリスト。 |
宣言的パイプラインでは、トップレベルの 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 ボタンをクリックします。次のオプションを使用できます。
内容 | 説明 | 環境変数 |
---|---|---|
ホスト名 | Datadog に送信されるすべてのイベントで使用するホスト名。 | DATADOG_JENKINS_PLUGIN_HOSTNAME |
除外されるジョブ | 監視対象から除外したいジョブ名を指定する正規表現を記載したカンマ区切りリストです。例: susans-job,johns-.*,prod_folder/prod_release | DATADOG_JENKINS_PLUGIN_EXCLUDED |
含まれるジョブ | 監視対象に含めたいジョブ名を指定する正規表現を記載したカンマ区切りリストです。例: susans-job,johns-.*,prod_folder/prod_release | DATADOG_JENKINS_PLUGIN_INCLUDED |
グローバルタグファイル | タグのカンマ区切りリストを含むワークスペースファイルへのパスです (パイプラインのジョブとは互換不能) 。 | DATADOG_JENKINS_PLUGIN_GLOBAL_TAG_FILE |
グローバルタグ | すべてのメトリクス、イベント、サービスチェックを適用するためのカンマ区切りのリストです。タグにはマスターの jenkins インスタンスで定義される環境変数を含めることができます。 | DATADOG_JENKINS_PLUGIN_GLOBAL_TAGS |
グローバルジョブタグ | ジョブとそのジョブに適用するタグのリストを照合するための正規表現を記載したカンマ区切りリストです。タグにはマスターの jenkins インスタンスで定義される環境変数を含めることができます。注: タグで $ 記号を用いて正規表現に一致したグループを参照することができます。例: (.*?)_job_(*?)_release, owner:$1, release_env:$2, optional:Tag3 | DATADOG_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#onStarted | branch , event_type , jenkins_url , job , node , user_id | jenkins.job.started |
ビルド中止 | RunListener#onDeleted | branch , event_type , jenkins_url , job , node , user_id | jenkins.job.aborted |
ビルド完了 | RunListener#onCompleted | branch , event_type , jenkins_url , job , node , result , user_id | jenkins.job.completed |
SCM チェックアウト | SCMListener#onCheckout | branch , event_type , jenkins_url , job , node , user_id | jenkins.scm.checkout |
注: event_type
は上記のイベントとメトリクスに対して常に default
に設定されます。
イベント名 | トリガー | デフォルトのタグ | 関連するレートメトリクス |
---|---|---|---|
コンピューターのオンライン | ComputerListener#onOnline | event_type , jenkins_url , node_hostname , node_name , node_label | jenkins.computer.online |
コンピューターのオフライン | ComputerListener#onOffline | event_type , jenkins_url , node_hostname , node_name , node_label | jenkins.computer.offline |
コンピューターの一時オンライン | ComputerListener#onTemporarilyOnline | event_type , jenkins_url , node_hostname , node_name , node_label | jenkins.computer.temporarily_online |
コンピューターの一時オフライン | ComputerListener#onTemporarilyOffline | event_type , jenkins_url , node_hostname , node_name , node_label | jenkins.computer.temporarily_offline |
コンピューターの起動失敗 | ComputerListener#onLaunchFailure | event_type , jenkins_url , node_hostname , node_name , node_label | jenkins.computer.launch_failure |
アイテムの作成 | ItemListener#onCreated | event_type , jenkins_url , user_id | jenkins.item.created |
アイテムの削除 | ItemListener#onDeleted | event_type , jenkins_url , user_id | jenkins.item.deleted |
アイテムの更新 | ItemListener#onUpdated | event_type , jenkins_url , user_id | jenkins.item.updated |
アイテムのコピー | ItemListener#onCopied | event_type , jenkins_url , user_id | jenkins.item.copied |
アイテムの場所変更 | ItemListener#onLocationChanged | event_type , jenkins_url , user_id | jenkins.item.location_changed |
構成の変更 | SaveableListener#onChange | event_type , jenkins_url , user_id | jenkins.config.changed |
注: event_type
は上記のイベントとメトリクスに対して常に system
に設定されます。
イベント名 | トリガー | デフォルトのタグ | 関連するレートメトリクス |
---|---|---|---|
ユーザー認証成功 | SecurityListener#authenticated | event_type , jenkins_url , user_id | jenkins.user.authenticated |
ユーザー認証失敗 | SecurityListener#failedToAuthenticate | event_type , jenkins_url , user_id | jenkins.user.access_denied |
ユーザーのログアウト | SecurityListener#loggedOut | event_type , jenkins_url , user_id | jenkins.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.mtbf | MTBF: 最後に成功したジョブから現在失敗したジョブまでの時間 | branch , jenkins_url , job , node , result , user_id |
jenkins.job.mttr | MTTR: 最後に失敗したジョブから現在成功したジョブまでの時間 | 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_url 、job 、user_id 、stage_name 、stage_depth 、stage_parent 、result |
jenkins.job.stage_pause_duration | 個々のステージの一時停止期間(ミリ秒)。 | jenkins_url 、job 、user_id 、stage_name 、stage_depth 、stage_parent 、result |
jenkins.job.stage_completed | ステージの完了レート | jenkins_url 、job 、user_id 、stage_name 、stage_depth 、stage_parent 、result |
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_url 、job_name |
jenkins.queue.job.buildable | ジョブがキューでビルド可能になった回数。 | jenkins_url 、job_name |
jenkins.queue.job.pending | ジョブがキューで保留された回数。 | jenkins_url 、job_name |
jenkins.queue.job.stuck | ジョブがキューでスタックした回数。 | jenkins_url 、job_name |
jenkins.queue.job.blocked | ジョブがキューでブロックされた回数。 | jenkins_url 、job_name |
jenkins.scm.checkout | SCM チェックアウトのレート | 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 |
注: このコンフィギュレーションは、Datadog Agent コンフィギュレーションを使用するものにのみ適用されます。
Datadog Agent で、ログの収集はデフォルトで無効になっています。以下のように、datadog.yaml
ファイルでこれを有効にします。
logs_enabled: true
Jenkins ログを収集するには、次のように conf.d/jenkins.d
内に conf.yaml
を作成して、Agent のカスタムログソースファイルを作成します。
logs:
- type: tcp
port: <PORT>
service: <SERVICE>
source: jenkins
Jenkins では、上記で指定したポートを Log Collection Port
として登録します。環境変数、Groovy スクリプト、Jenkins UI で設定することが可能です。
ビルドステータス jenkins.job.status
にデフォルトタグを適用: jenkins_url、
job、
node、
user_id`
このプラグイン jenkinsci/datadog-plugin/issuesに関する問題はすべて、GitHub に搭載の問題追跡システムを使用して追跡を行います。 しかし、Jenkins プラグインのホスティング状況に応じて、JIRA に課題が作成される場合があります。関連する課題の投稿については、 Jenkins の課題ページをご参照ください。
注: Datadog に関連する JIRA の課題で未解決のものが存在します。
CHANGELOG.md をご参照ください。
開発に対するアイデアを共有いただけることに、まずは深く感謝を申し上げます。
課題やプルリクエストの送信前に、ドキュメント寄稿ガイドラインをお読みください。 開発用ドキュメントでも、ローカル開発環境の準備などに関するヒントをご紹介しています。