Jenkins
Security Monitoring is now available Security Monitoring is now available

Jenkins

A Jenkins plugin for automatically forwarding metrics, events, and service checks to a Datadog account.

Note: The Jenkins CI plugin page for this plugin references this documentation.

Setup

Installation

This plugin requires Jenkins 1.632 or newer.

This plugin can be installed from the Update Center (found at Manage Jenkins -> Manage Plugins) in your Jenkins installation:

  1. Select the Available tab, search for Datadog, and select the checkbox next to Datadog Plugin.
  2. Install the plugin by using one of the two install buttons at the bottom of the screen.
  3. To verify the plugin is installed, search for Datadog Plugin on the Installed tab.

Continue below for configuration.

Note: If you see an unexpected version of the Datadog Plugin, run Check Now from the Manage Jenkins -> Manage Plugins screen.

Configuration

There are two ways to configure your plugin to submit data to Datadog:

  • RECOMMENDED: Using a DogStatsD server / Datadog Agent that acts as a forwarder between Jenkins and Datadog.
    • Build Logs collection only works with a full Datadog Agent installed.
  • Sending data directly to Datadog through HTTP.
    • The HTTP client implementation used is blocking with a timeout duration of 1 minute. If there is a connection problem with Datadog, it may slow your Jenkins instance down.

The configuration can be done from the plugin user interface with a Groovy script, or through environment variables.

Plugin user interface

To configure your Datadog Plugin, navigate to the Manage Jenkins -> Configure System page on your Jenkins installation. Once there, scroll down to find the Datadog Plugin section:

HTTP forwarding
  1. Select the radio button next to Use Datadog API URL and Key to report to Datadog (selected by default).
  2. Paste your Datadog API key in the API Key textbox on the Jenkins configuration screen.
  3. Test your Datadog API key by using the Test Key button on the Jenkins configuration screen directly below the API key textbox.
  4. (optional) Enter your Datadog Log Intake URL.
  5. Save your configuration.
DogStatsD forwarding
  1. Select the radio button next to Use the Datadog Agent to report to Datadog.
  2. Specify your DogStatsD server hostname and port.
  3. (optional) Enter your Log Collection Port and configure log collection.
  4. Save your configuration.

Groovy script

Configure your Datadog plugin to forward data through HTTP or DogStatsD using the Groovy scripts below. Configuring the plugin this way might be useful if you’re running your Jenkins Master in a Docker container using the official Jenkins Docker image or any derivative that supports plugins.txt and Groovy init scripts.

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

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

// If you want to use Datadog API URL and Key to report to Datadog
d.setReportWith('HTTP')
d.setTargetApiURL('https://api.datadoghq.com/api/')
d.setTargetApiKey('<DATADOG_API_KEY>')

// Customization, see dedicated section below
d.setBlacklist('job1,job2')

// If you want to collect logs
d.setLogIntakeUrl('https://http-intake.logs.datadoghq.com/v1/input/')

// Save config
d.save()
DogStatsD forwarding
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)

// If you want to collect logs
d.setLogCollectionPort(8125)

// Customization, see dedicated section below
d.setBlacklist('job1,job2')

// Save config
d.save()

Environment variables

Configure your Datadog plugin using environment variables with the DATADOG_JENKINS_PLUGIN_REPORT_WITH variable, which specifies the report mechanism to use.

HTTP forwarding
  1. Set the DATADOG_JENKINS_PLUGIN_REPORT_WITH variable to HTTP.
  2. Set the DATADOG_JENKINS_PLUGIN_TARGET_API_URL variable, which specifies the Datadog API endpoint (defaults to https://api.datadoghq.com/api/).
  3. Set the DATADOG_JENKINS_PLUGIN_TARGET_API_KEY variable, which specifies your Datadog API key.
  4. (optional) Set the DATADOG_JENKINS_PLUGIN_TARGET_LOG_INTAKE_URL variable, which specifies the Datadog Log Intake URL (defaults to https://http-intake.logs.datadoghq.com/v1/input/).
DogStatsD forwarding
  1. Set the DATADOG_JENKINS_PLUGIN_REPORT_WITH variable to DSD.
  2. Set the DATADOG_JENKINS_PLUGIN_TARGET_HOST variable, which specifies the DogStatsD server host (defaults to localhost).
  3. Set the DATADOG_JENKINS_PLUGIN_TARGET_PORT variable, which specifies the DogStatsD server port (defaults to 8125).
  4. (optional) Set the DATADOG_JENKINS_PLUGIN_TARGET_LOG_COLLECTION_PORT variable, which specifies the Datadog Agent log collection port.

Logging

Logging is done by utilizing the java.util.Logger, which follows the best logging practices for Jenkins. To obtain logs, follow the directions in the Jenkins logging documentation. When adding a logger, all Datadog plugin functions start with org.datadog.jenkins.plugins.datadog. and the function name you are after should autopopulate. As of this writing, the only function available was org.datadog.jenkins.plugins.datadog.listeners.DatadogBuildListener.

Customization

Global customization

To customize your global configuration, in Jenkins navigate to Manage Jenkins -> Configure System then click the Advanced button. The following options are available:

CustomizationDescriptionEnvironment variable
Blacklisted jobsA comma-separated list of regex used to exclude job names from monitoring, for example: susans-job,johns-.*,prod_folder/prod_release.DATADOG_JENKINS_PLUGIN_BLACKLIST
Whitelisted jobsA comma-separated list of regex used to include job names for monitoring, for example: susans-job,johns-.*,prod_folder/prod_release.DATADOG_JENKINS_PLUGIN_WHITELIST
Global tag fileThe path to a workspace file containing a comma separated list of tags (not compatible with pipeline jobs).DATADOG_JENKINS_PLUGIN_GLOBAL_TAG_FILE
Global tagsA comma-separated list of tags to apply to all metrics, events, and service checks.DATADOG_JENKINS_PLUGIN_GLOBAL_TAGS
Global job tagsA comma separated list of regex to match a job and a list of tags to apply to that job. Note: Tags can reference match groups in the regex using the $ symbol, for example: (.*?)_job_(*?)_release, owner:$1, release_env:$2, optional:Tag3DATADOG_JENKINS_PLUGIN_GLOBAL_JOB_TAGS
Send security audit eventsSubmits the Security Events Type of events and metrics (enabled by default).DATADOG_JENKINS_PLUGIN_EMIT_SECURITY_EVENTS
Send system eventsSubmits the System Events Type of events and metrics (enabled by default).DATADOG_JENKINS_PLUGIN_EMIT_SYSTEM_EVENTS
Enable Log CollectionCollect and Submit build logs (disabled by default).DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS

Job customization

From a job specific configuration page:

CustomizationDescription
Custom tagsSet from a File in the job workspace (not compatible with pipeline jobs) or as text Properties directly from the configuration page. If set, this overrides the Global Job Tags configuration.
Send source control management eventsSubmits the Source Control Management Events Type of events and metrics (enabled by default).

Data collected

This plugin is collecting the following events, metrics, and service checks:

Events

Default events type

Event nameTriggered onDefault tagsAssociated RATE metric
Build startedRunListener#onStartedbranch, event_type, jenkins_url, job, node, user_idjenkins.job.started
Build abortedRunListener#onDeletedbranch, event_type, jenkins_url, job, node, user_idjenkins.job.aborted
Build completedRunListener#onCompletedbranch, event_type, jenkins_url, job, node, result, user_idjenkins.job.completed
SCM checkoutSCMListener#onCheckoutbranch, event_type, jenkins_url, job, node, user_idjenkins.scm.checkout

NOTE: event_type is always set to default for above events and metrics.

Systems events type

Event nameTriggered onDefault tagsAssociated RATE metric
Computer OnlineComputerListener#onOnlineevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.online
Computer OfflineComputerListener#onOfflineevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.offline
Computer TemporarilyOnlineComputerListener#onTemporarilyOnlineevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.temporarily_online
Computer TemporarilyOfflineComputerListener#onTemporarilyOfflineevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.temporarily_offline
Computer LaunchFailureComputerListener#onLaunchFailureevent_type, jenkins_url, node_hostname, node_name, node_labeljenkins.computer.launch_failure
Item CreatedItemListener#onCreatedevent_type, jenkins_url, user_idjenkins.item.created
Item DeletedItemListener#onDeletedevent_type, jenkins_url, user_idjenkins.item.deleted
Item UpdatedItemListener#onUpdatedevent_type, jenkins_url, user_idjenkins.item.updated
Item CopiedItemListener#onCopiedevent_type, jenkins_url, user_idjenkins.item.copied
Item Location ChangedItemListener#onLocationChangedevent_type, jenkins_url, user_idjenkins.item.location_changed
Config ChangedSaveableListener#onChangeevent_type, jenkins_url, user_idjenkins.config.changed

NOTE: event_type is always set to system for above events and metrics.

Security events type

Event nameTriggered onDefault tagsAssociated RATE metric
User AuthenticatedSecurityListener#authenticatedevent_type, jenkins_url, user_idjenkins.user.authenticated
User failed To AuthenticateSecurityListener#failedToAuthenticateevent_type, jenkins_url, user_idjenkins.user.access_denied
User loggedOutSecurityListener#loggedOutevent_type, jenkins_url, user_idjenkins.user.logout

NOTE: event_type is always set to security for above events and metrics.

Metrics

Metric NameDescriptionDefault Tags
jenkins.computer.launch_failureRate of computer launch failures.jenkins_url
jenkins.computer.offlineRate of computer going offline.jenkins_url
jenkins.computer.onlineRate of computer going online.jenkins_url
jenkins.computer.temporarily_offlineRate of computer going temporarily offline.jenkins_url
jenkins.computer.temporarily_onlineRate of computer going temporarily online.jenkins_url
jenkins.config.changedRate of configs being changed.jenkins_url, user_id
jenkins.executor.countExecutor count.jenkins_url, node_hostname, node_name, node_label
jenkins.executor.freeNumber of unused executor.jenkins_url, node_hostname, node_name, node_label
jenkins.executor.in_useNumber of idle executor.jenkins_url, node_hostname, node_name, node_label
jenkins.item.copiedRate of items being copied.jenkins_url, user_id
jenkins.item.createdRate of items being created.jenkins_url, user_id
jenkins.item.deletedRate of items being deleted.jenkins_url, user_id
jenkins.item.location_changedRate of items being moved.jenkins_url, user_id
jenkins.item.updatedRate of items being updated.jenkins_url, user_id
jenkins.job.abortedRate of aborted jobs.branch, jenkins_url, job, node, user_id
jenkins.job.build_durationBuild duration without pause (in seconds).branch, jenkins_url, job, node, result, user_id
jenkins.job.completedRate of completed jobs.branch, jenkins_url, job, node, result, user_id
jenkins.job.cycletimeBuild Cycle Time.branch, jenkins_url, job, node, result, user_id
jenkins.job.durationBuild duration (in seconds).branch, jenkins_url, job, node, result, user_id
jenkins.job.feedbacktimeFeedback time from code commit to job failure.branch, jenkins_url, job, node, result, user_id
jenkins.job.leadtimeBuild Lead Time.branch, jenkins_url, job, node, result, user_id
jenkins.job.mtbfMTBF, time between last successful job and current failed job.branch, jenkins_url, job, node, result, user_id
jenkins.job.mttrMTTR: time between last failed job and current successful job.branch, jenkins_url, job, node, result, user_id
jenkins.job.pause_durationPause duration of build job (in seconds).branch, jenkins_url, job, node, result, user_id
jenkins.job.startedRate of started jobs.branch, jenkins_url, job, node, user_id
jenkins.job.stage_durationDuration of individual stages.jenkins_url, job, user_id, stage_name, stage_depth, stage_parent
jenkins.job.waitingTime spent waiting for job to run (in milliseconds).branch, jenkins_url, job, node, user_id
jenkins.node.countTotal number of node.jenkins_url
jenkins.node.offlineOffline nodes count.jenkins_url
jenkins.node.onlineOnline nodes count.jenkins_url
jenkins.node_status.countIf this node is present.jenkins_url, node_hostname, node_name, node_label
jenkins.node_status.upIf a given node is online, value 1. Otherwise, 0.jenkins_url, node_hostname, node_name, node_label
jenkins.plugin.countPlugins count.jenkins_url
jenkins.project.countProject count.jenkins_url
jenkins.queue.sizeQueue Size.jenkins_url
jenkins.queue.buildableNumber of Buildable item in Queue.jenkins_url
jenkins.queue.pendingNumber of Pending item in Queue.jenkins_url
jenkins.queue.stuckNumber of Stuck item in Queue.jenkins_url
jenkins.queue.blockedNumber of Blocked item in Queue.jenkins_url
jenkins.queue.job.in_queueNumber of times a Job has been in a Queue.jenkins_url, job_name
jenkins.queue.job.buildableNumber of times a Job has been Buildable in a Queue.jenkins_url, job_name
jenkins.queue.job.pendingNumber of times a Job has been Pending in a Queue.jenkins_url, job_name
jenkins.queue.job.stuckNumber of times a Job has been Stuck in a Queue.jenkins_url, job_name
jenkins.queue.job.blockedNumber of times a Job has been Blocked in a Queue.jenkins_url, job_name
jenkins.scm.checkoutRate of SCM checkouts.branch, jenkins_url, job, node, user_id
jenkins.user.access_deniedRate of users failing to authenticate.jenkins_url, user_id
jenkins.user.authenticatedRate of users authenticating.jenkins_url, user_id
jenkins.user.logoutRate of users logging out.jenkins_url, user_id

Log Collection for Agents

Note: This configuration only applies to those using the Datadog Agent configuration.

  1. Collecting logs is disabled by default in the Datadog Agent, enable it in your datadog.yaml file:

    logs_enabled: true
  2. To collect Jenkins logs, create a custom log source file for your Agent by creating a conf.yaml inside conf.d/jenkins.d with the following:

    logs:
      - type: tcp 
        port: <PORT> 
        service: <SERVICE>
        source: jenkins
  3. In Jenkins, submit the port you specified above as the Log Collection Port. You can set this using env vars, a groovy script, or the Jenkins UI.

  4. Restart the Agent.

Service checks

Build status jenkins.job.status with the default tags: : jenkins_url, job, node, result, user_id

Issue Tracking

GitHub’s built-in issue tracking system is used to track all issues relating to this plugin: jenkinsci/datadog-plugin/issues. However, given how Jenkins plugins are hosted, there may be issues that are posted to JIRA as well. You can check this jenkins issue for those issue postings.

Note: Unresolved issues on JIRA mentioning Datadog.

Changes

See the CHANGELOG.md.

How to contribute code

First of all and most importantly, thank you for sharing.

Checkout the contributing guidelines before you submit an issue or a pull request.
Checkout the development document for tips on spinning up a quick development environment locally.