--- title: Jenkins description: >- Automatically forward your Jenkins metrics, events, and service checks to Datadog. breadcrumbs: Docs > Integrations > Jenkins --- # Jenkins A Jenkins plugin for automatically forwarding metrics, events, and service checks to a Datadog account. **Note**: The [Jenkins CI plugin page](https://plugins.jenkins.io/datadog) for this plugin references this documentation. ## Setup{% #setup %} ### Installation{% #installation %} *This plugin requires [Jenkins 2.361.4](http://updates.jenkins-ci.org/download/war/2.361.4/jenkins.war) and Java 11.* *For older versions of Jenkins (i.e 1.632+), you can find the 1.2.0 version of the plugin [here](https://updates.jenkins.io/download/plugins/datadog/).* This plugin can be installed from the [Update Center](https://wiki.jenkins-ci.org/display/JENKINS/Plugins#Plugins-Howtoinstallplugins) (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`. 1. Install the plugin by using one of the two install buttons at the bottom of the screen. 1. 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{% #configuration %} There are two ways to configure your plugin to submit data to Datadog: - Using a Datadog Agent that acts as a forwarder between Jenkins and Datadog (recommended). - When using a DogStatsD server instead of a full Datadog Agent, only metrics and events are supported. - For data submitted from an external host, the Datadog Agent requires the following configuration: `dogstatsd_non_local_traffic: true` and `apm_non_local_traffic: true`. This can be configured using the `datadog.yaml` [configuration file](https://docs.datadoghq.com/developers/dogstatsd/?tab=containeragent#). - 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{% #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{% #http-forwarding %} 1. Select the radio button next to **Use Datadog site and API key to report to Datadog** (selected by default). 1. Select your [Datadog site](https://docs.datadoghq.com/getting_started/site/#access-the-datadog-site) in the **Pick a site** dropdown. 1. Paste your [Datadog API key](https://app.datadoghq.com/account/settings#api) in the `API Key` textbox on the Jenkins configuration screen. If you would like to store your API key with the [Credentails Manager](https://www.jenkins.io/doc/book/using/using-credentials/), create a Credential for the API key and select that credential in the `Select from credentials` dropdown. 1. Test your Datadog API key by using the `Test Key` button on the Jenkins configuration screen directly below the API key textbox. 1. (optional) Enter the name of the host that you use to access Datadog UI (e.g. `app.datadoghq.com`) in the `Datadog App hostname` field. 1. (optional) Enter the hostname of the Jenkins server in the Advanced tab to include it with the events. 1. (optional) Enter your [Datadog Log Intake URL](https://docs.datadoghq.com/logs/log_collection/?tab=http) and select "Enable Log Collection" in the Advanced tab. 1. (optional) Select "Enable CI Visibility", optionally configuring your CI Instance name. 1. Save your configuration. ##### Datadog Agent forwarding{% #datadog-agent-forwarding %} 1. Select the radio button next to **Use the Datadog Agent to report to Datadog**. 1. Specify your Datadog Agent `hostname` and `port`. 1. (optional) Enter the name of the host that you use to access Datadog UI (e.g. `app.datadoghq.com`) in the `Datadog App hostname` field. 1. (optional) Enter the hostname of the Jenkins server in the Advanced tab to include it with the events. 1. (optional) Enter your Log Collection Port, configure log collection in the Datadog Agent, and select "Enable Log Collection". 1. (optional) Enter your Trace Collection Port and select "Enable CI Visibility", optionally configuring your CI Instance name. 1. Save your configuration. ### Port 7 usage{% #port-7-usage %} When a Jenkins Agent node connects to the controller, the plugin on the controller sends a corresponding event to Datadog. During event creation, the plugin calls Jenkins core APIs to retrieve Agent metadata (such as hostname and labels). These API calls internally perform several checks, including a reachability test using java.net.InetAddress#isReachable. This call sends a TCP SYN packet from the controller to port 7 on the Agent node. The server on the Agent node responds with a RST packet (Reset). This is a common technique used to verify network connectivity between services. The fact that it gets a RST response (rather than no response) confirms that: 1. The network path exists 1. The server is reachable 1. The server is actively rejecting the connection (which is what we want) #### Groovy script{% #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](https://github.com/jenkinsci/docker) or any derivative that supports `plugins.txt` and Groovy init scripts. ##### HTTP forwarding using Groovy{% #http-forwarding-using-groovy %} ```groovy import hudson.util.Secret import jenkins.model.Jenkins import org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration import org.datadog.jenkins.plugins.datadog.configuration.DatadogApiConfiguration import org.datadog.jenkins.plugins.datadog.configuration.api.intake.DatadogIntakeSite import org.datadog.jenkins.plugins.datadog.configuration.api.intake.DatadogSite import org.datadog.jenkins.plugins.datadog.configuration.api.key.DatadogTextApiKey def jenkins = Jenkins.getInstance() def datadog = jenkins.getDescriptorByType(DatadogGlobalConfiguration) def site = new DatadogIntakeSite(DatadogSite.US1) // pick your Datadog site def apiKey = new DatadogTextApiKey(Secret.fromString('')) // or `new DatadogCredentialsApiKey('')` datadog.datadogClientConfiguration = new DatadogApiConfiguration(site, apiKey) datadog.datadogAppHostname = 'app.datadoghq.com' // the name of the host that you use to access Datadog UI datadog.collectBuildLogs = true // if you want to collect logs datadog.enableCiVisibility = true // if you want to enable CI Visibility // Customization, see dedicated section below datadog.excluded = 'job1,job2' // Save config datadog.save() ``` ##### Datadog Agent forwarding using Groovy{% #datadog-agent-forwarding-using-groovy %} ```groovy import jenkins.model.Jenkins import org.datadog.jenkins.plugins.datadog.DatadogGlobalConfiguration import org.datadog.jenkins.plugins.datadog.configuration.DatadogAgentConfiguration def jenkins = Jenkins.getInstance() def datadog = jenkins.getDescriptorByType(DatadogGlobalConfiguration) def agentHost = 'localhost' def agentPort = 8125 def agentLogCollectionPort = 10518 def agentTraceCollectionPort = 8126 datadog.datadogClientConfiguration = new DatadogAgentConfiguration(agentHost, agentPort, agentLogCollectionPort, agentTraceCollectionPort) datadog.datadogAppHostname = 'app.datadoghq.com' // the name of the host that you use to access Datadog UI datadog.collectBuildLogs = true // if you want to collect logs datadog.enableCiVisibility = true // if you want to enable CI Visibility // Customization, see dedicated section below datadog.excluded = 'job1,job2' // Save config datadog.save() ``` #### Environment variables{% #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 using environment variables{% #http-forwarding-using-environment-variables %} 1. Set the `DATADOG_JENKINS_PLUGIN_REPORT_WITH` variable to `HTTP`. 1. Set the `DATADOG_JENKINS_PLUGIN_DATADOG_SITE` variable, which specifies the [Datadog site](https://docs.datadoghq.com/getting_started/site/#access-the-datadog-site) (defaults to US1). 1. Set the `DATADOG_JENKINS_PLUGIN_TARGET_API_KEY` variable, which specifies your [Datadog API key](https://app.datadoghq.com/account/settings#api). 1. (optional) Set the `DATADOG_JENKINS_PLUGIN_DATADOG_APP_HOSTNAME` variable to the name of the host that you use to access Datadog UI (e.g. `app.datadoghq.com`) 1. (optional) Log Collection: - Set the `DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS` variable to `true` in order to enable log collection (disabled by default). (optional) CI Visibility (trace collection): - Set the `DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY` variable to `true` in order to enable CI Visibility (disabled by default). - Set the `DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME` variable, which specifies the name of the Jenkins instance for CI Visibility (defaults to `jenkins`). ##### Datadog Agent forwarding using environment variables{% #datadog-agent-forwarding-using-environment-variables %} 1. Set the `DATADOG_JENKINS_PLUGIN_REPORT_WITH` variable to `DSD`. 1. Set the `DATADOG_JENKINS_PLUGIN_TARGET_HOST` variable, which specifies the DogStatsD server host (defaults to `localhost`). 1. Set the `DATADOG_JENKINS_PLUGIN_TARGET_PORT` variable, which specifies the DogStatsD server port (defaults to `8125`). 1. (optional) Set the `DATADOG_JENKINS_PLUGIN_DATADOG_APP_HOSTNAME` variable to the name of the host that you use to access Datadog UI (e.g. `app.datadoghq.com`) 1. (optional) Log Collection: - Enable log collection in the Datadog Agent. - Set the `DATADOG_JENKINS_PLUGIN_COLLECT_BUILD_LOGS` variable to `true` in order to enable log collection (disabled by default). - Set the `DATADOG_JENKINS_PLUGIN_TARGET_LOG_COLLECTION_PORT` variable, which specifies the Datadog Agent log collection port. 1. (optional) CI Visibility (trace collection): - Set the `DATADOG_JENKINS_PLUGIN_ENABLE_CI_VISIBILITY` variable to `true` in order to enable CI Visibility (disabled by default). - Set the `DATADOG_JENKINS_PLUGIN_TARGET_TRACE_COLLECTION_PORT` variable, which specifies the Datadog Agent trace collection port (defaults to `8126`). - Set the `DATADOG_JENKINS_PLUGIN_CI_VISIBILITY_CI_INSTANCE_NAME` variable, which specifies the name of the Jenkins instance for CI Visibility (defaults to `jenkins`). Additionally, you can use the standard Datadog environment variables: - Set the `DD_AGENT_HOST` variable, which specifies the Datadog Agent host. - Set the `DD_AGENT_PORT` variable, which specifies the DogStatsD server port. - Set the `DD_TRACE_AGENT_PORT` variable, which specifies the Datadog Agent trace collection port. - Set the `DD_TRACE_AGENT_URL` variable, which specifies the Datadog Agent URL to send traces. When set this takes precedence over `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT`. The environment variables with the `DATADOG_JENKINS_PLUGIN` namespace take precedence over the standard Datadog environment variables. #### Logging{% #logging %} Logging is done by utilizing the `java.util.Logger`, which follows the [best logging practices for Jenkins](https://wiki.jenkins-ci.org/display/JENKINS/Logging). The plugin automatically registers a custom logger named "Datadog Plugin Logs" that writes the plugin's logs with level `INFO` or higher. The custom logger registration can be disabled by setting the `DD_JENKINS_PLUGIN_LOG_RECORDER_ENABLED` environment variable to `false`. If you want to see the plugin logs with maximum detail, manually change the level of the custom logger to `ALL`. ## Customization{% #customization %} ### Pipeline customization{% #pipeline-customization %} The Datadog plugin adds a `datadog` step that provides some configuration option for your pipeline-based jobs. | Option (type) | Description | | ------------------------- | --------------------------------------------------------------------------- | | `collectLogs` (`boolean`) | When log collection is disabled globally, this enables it for the pipeline. | | `tags` (`String[]`) | A list of tags to attach to all the data collected about the pipeline. | In declarative pipelines, add the step to a top-level `options` block like so: ```groovy pipeline { agent any options { datadog(collectLogs: true, tags: ["foo:bar", "bar:baz"]) } stages { stage('Example') { steps { echo "Hello world." } } } } ``` In scripted pipeline, wrap the relevant section with the datadog step like so: ```groovy datadog(collectLogs: true, tags: ["foo:bar", "bar:baz"]) { node { stage('Example') { echo "Hello world." } } } ``` **Note**: Pipeline customizations are only registered after a job has started. Tags specified in pipeline customization will not be associated with `jenkins.job.started`. ### Global 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: | Customization | Description | Environment variable | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | Hostname | A hostname to use in every event sent to Datadog. | `DATADOG_JENKINS_PLUGIN_HOSTNAME` | | Excluded jobs | A comma-separated list of regex used to exclude job names from monitoring, for example: `susans-job,johns-.*,prod_folder/prod_release`. This setting affects all aspects of the plugin: events, metrics, logs, CI visibility. | `DATADOG_JENKINS_PLUGIN_EXCLUDED` | | Included jobs | A comma-separated list of regex used to include job names for monitoring, for example: `susans-job,johns-.*,prod_folder/prod_release`. This setting affects all aspects of the plugin: events, metrics, logs, CI visibility. | `DATADOG_JENKINS_PLUGIN_INCLUDED` | | Global tag file | The path to a workspace file containing a comma separated list of tags (not compatible with pipeline jobs). | `DATADOG_JENKINS_PLUGIN_GLOBAL_TAG_FILE` | | Global tags | A comma-separated list of tags to apply to all metrics, events, and service checks. Tags can include environment variables that are defined in the master jenkins instance. | `DATADOG_JENKINS_PLUGIN_GLOBAL_TAGS` | | Global job tags | A comma separated list of regex to match a job and a list of tags to apply to that job. Tags can include environment variables that are defined in the master jenkins instance. **Note**: Tags can reference match groups in the regex using the `$` symbol, for example: `(.*?)_job_(*?)_release, owner:$1, release_env:$2, optional:Tag3` | `DATADOG_JENKINS_PLUGIN_GLOBAL_JOB_TAGS` | | Send security audit events | Submits the `Security Events Type` of events and metrics (enabled by default). | `DATADOG_JENKINS_PLUGIN_EMIT_SECURITY_EVENTS` | | Send system events | Submits the `System Events Type` of events and metrics (enabled by default). | `DATADOG_JENKINS_PLUGIN_EMIT_SYSTEM_EVENTS` | | Include events to send | A comma-separated list of event name strings to send, regardless of the event type being enabled/disabled. | `DATADOG_JENKINS_PLUGIN_INCLUDE_EVENTS` | | Exclude events to send | A comma-separated list of event name strings not to send, regardless of the event type being enabled/disabled. | `DATADOG_JENKINS_PLUGIN_EXCLUDE_EVENTS` | ### Job customization{% #job-customization %} From a job specific configuration page: | Customization | Description | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Custom tags | Set 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 events | Submits the `Source Control Management Events Type` of events and metrics (enabled by default). | ### Test Optimization Configuration{% #test-optimization-configuration %} The plugin can automatically configure Datadog [Test Optimization](https://docs.datadoghq.com/tests/) for a job or a pipeline (see the Test Optimization [documentation for your language](https://docs.datadoghq.com/tests/setup/) to make sure that the testing framework that you use is supported; also note that automatic configuration is not supported for tests that are executed inside containers - follow [manual instrumentation steps](https://docs.datadoghq.com/tests/setup/) to enable Test Optimization for containerized test runs). Before enabling Test Optimization, be sure to properly configure the plugin to submit data to Datadog. There are two options to enable automatic Test Optimization configuration: 1. Using Jenkins UI (available in the plugin v5.6.0 or newer): go to the **Configure** page of the job or pipeline whose tests need to be traced, tick the **Enable Datadog Test Optimization** checkbox in the **General** section, and save your changes. This option is unavailable if you are using Multibranch Pipelines, Organization Folders, or other types of pipelines that are configured entirely with `Jenkinsfile`. 1. Using `datadog` pipeline step (available in the plugin v5.6.2 or newer): In declarative pipelines, add the step to a top-level `options` block like so: ```groovy pipeline { agent any options { datadog(testOptimization: [ 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", "RUBY", "GO") additionalVariables: ["my-var": "value"] // additional tracer configuration settings (optional) ]) } stages { stage('Example') { steps { echo "Hello world." } } } } ``` In scripted pipelines, wrap the relevant section with the `datadog` step like so: ```groovy datadog(testOptimization: [ enabled: true, serviceName: "my-service", languages: ["JAVA"], additionalVariables: [:] ]) { node { stage('Example') { echo "Hello world." } } } ``` The other `datadog` settings, such as `collectLogs` or `tags` can be added alongside the `testOptimization` block. Please bear in mind that Test Optimization is a separate Datadog product that is billed separately. ## Data collected{% #data-collected %} This plugin is collecting the following events, metrics, and service checks: ### Events{% #events %} #### Default events type{% #default-events-type %} | Event name | Triggered on | Default tags | Associated RATE metric | | -------------- | ------------------------- | ------------------------------------------------------------------------- | ----------------------- | | BuildStarted | `RunListener#onStarted` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `user_id` | `jenkins.job.started` | | BuildAborted | `RunListener#onDeleted` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `user_id` | `jenkins.job.aborted` | | BuildCompleted | `RunListener#onCompleted` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `result`, `user_id` | `jenkins.job.completed` | | SCMCheckout | `SCMListener#onCheckout` | `branch`, `event_type`, `jenkins_url`, `job`, `node`, `user_id` | `jenkins.scm.checkout` | NOTE: `event_type` is always set to `default` for above events and metrics. #### Systems events type{% #systems-events-type %} | Event name | Triggered on | Default tags | Associated RATE metric | | -------------------------- | --------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------- | | ComputerOnline | `ComputerListener#onOnline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.online` | | ComputerOffline | `ComputerListener#onOffline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.offline` | | ComputerTemporarilyOnline | `ComputerListener#onTemporarilyOnline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.temporarily_online` | | ComputerTemporarilyOffline | `ComputerListener#onTemporarilyOffline` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.temporarily_offline` | | ComputerLaunchFailure | `ComputerListener#onLaunchFailure` | `event_type`, `jenkins_url`, `node_hostname`, `node_name`, `node_label` | `jenkins.computer.launch_failure` | | ItemCreated | `ItemListener#onCreated` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.created` | | ItemDeleted | `ItemListener#onDeleted` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.deleted` | | ItemUpdated | `ItemListener#onUpdated` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.updated` | | ItemCopied | `ItemListener#onCopied` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.copied` | | ItemLocationChanged | `ItemListener#onLocationChanged` | `event_type`, `jenkins_url`, `user_id` | `jenkins.item.location_changed` | NOTE: `event_type` is always set to `system` for above events and metrics. #### Security events type{% #security-events-type %} | Event name | Triggered on | Default tags | Associated RATE metric | | ------------------------ | --------------------------------------- | -------------------------------------- | ---------------------------- | | UserAuthenticated | `SecurityListener#authenticated` | `event_type`, `jenkins_url`, `user_id` | `jenkins.user.authenticated` | | UserFailedToAuthenticate | `SecurityListener#failedToAuthenticate` | `event_type`, `jenkins_url`, `user_id` | `jenkins.user.access_denied` | | UserLoggedOut | `SecurityListener#loggedOut` | `event_type`, `jenkins_url`, `user_id` | `jenkins.user.logout` | NOTE: `event_type` is always set to `security` for above events and metrics. #### Filtering events{% #filtering-events %} This plugin allows you to filter events by the event type as well as the specific event names listed above. To include/exclude all events of the system or security type: - **In the UI**: Uncheck the checkboxes for these events. - **In a groovy script**: Fetch the Datadog global descriptor and call either `d.setEmitSystemEvents()` or `d.setEmitSecurityEvents()`. - **In the environment variables section**: Set the environment variables for the emitting security or system events. To get more specific control over what events are sent, three configuration options are provided to allow a comma-separated include/exclude list of strings of event names. The include/exclude list has precedence over filtering by event type. For example, `security` events can be toggled off, but including `UserAuthenticated` takes precedence, so only `UserAuthenticated` events will be sent from the `security` type. In the UI, text boxes are provided for both the included and excluded lists. In a groovy script, the methods `d.setIncludeEvents()` and `d.setExcludeEvents()` accept a comma-separated list of event names as input which is another valid configuration method. Lastly, there are provided environment variables for manually setting included/excluded lists. NOTE: As mentioned in the job customization section, there are job-specific toggles to send `SCMCheckout` events. If the `SCMCheckout` event is excluded globally, this toggle will have no effect. ### Metrics{% #metrics %} | Metric Name | Description | Default Tags | | -------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `jenkins.computer.launch_failure` | Rate of computer launch failures. | `jenkins_url` | | `jenkins.computer.offline` | Rate of computer going offline. | `jenkins_url` | | `jenkins.computer.online` | Rate of computer going online. | `jenkins_url` | | `jenkins.computer.temporarily_offline` | Rate of computer going temporarily offline. | `jenkins_url` | | `jenkins.computer.temporarily_online` | Rate of computer going temporarily online. | `jenkins_url` | | `jenkins.config.changed` | Rate of configs being changed. | `jenkins_url`, `user_id` | | `jenkins.executor.count` | Executor count. | `jenkins_url`, `node_hostname`, `node_name`, `node_label` | | `jenkins.executor.free` | Number of unused executor. | `jenkins_url`, `node_hostname`, `node_name`, `node_label` | | `jenkins.executor.in_use` | Number of idle executor. | `jenkins_url`, `node_hostname`, `node_name`, `node_label` | | `jenkins.item.copied` | Rate of items being copied. | `jenkins_url`, `user_id` | | `jenkins.item.created` | Rate of items being created. | `jenkins_url`, `user_id` | | `jenkins.item.deleted` | Rate of items being deleted. | `jenkins_url`, `user_id` | | `jenkins.item.location_changed` | Rate of items being moved. | `jenkins_url`, `user_id` | | `jenkins.item.updated` | Rate of items being updated. | `jenkins_url`, `user_id` | | `jenkins.job.aborted` | Rate of aborted jobs. | `branch`, `jenkins_url`, `job`, `node`, `user_id` | | `jenkins.job.build_duration` | Build duration without pause (in seconds). | `branch`, `jenkins_url`, `job`, `node`, `result`, `user_id` | | `jenkins.job.completed` | Rate of completed jobs. | `branch`, `jenkins_url`, `job`, `node`, `result`, `user_id` | | `jenkins.job.cycletime` | Build Cycle Time (in seconds). | `branch`, `jenkins_url`, `job`, `node`, `result`, `user_id` | | `jenkins.job.duration` | Build duration (in seconds). | `branch`, `jenkins_url`, `job`, `node`, `result`, `user_id` | | `jenkins.job.feedbacktime` | Feedback time from code commit to job failure (in seconds). | `branch`, `jenkins_url`, `job`, `node`, `result`, `user_id` | | `jenkins.job.leadtime` | Build Lead Time. | `branch`, `jenkins_url`, `job`, `node`, `result`, `user_id` | | `jenkins.job.mtbf` | MTBF, time between last successful job and current failed job (in seconds). | `branch`, `jenkins_url`, `job`, `node`, `result`, `user_id` | | `jenkins.job.mttr` | MTTR: time between last failed job and current successful job (in seconds). | `branch`, `jenkins_url`, `job`, `node`, `result`, `user_id` | | `jenkins.job.pause_duration` | Pause duration of build job (in seconds). | `branch`, `jenkins_url`, `job`, `node`, `result`, `user_id` | | `jenkins.job.started` | Rate of started jobs. | `branch`, `jenkins_url`, `job`, `node`, `user_id` | | `jenkins.job.stage_duration` | Duration of individual stages. | `jenkins_url`, `job`, `user_id`, `stage_name`, `stage_depth`, `stage_parent`, `result` | | `jenkins.job.stage_pause_duration` | Pause duration of individual stages (in milliseconds). | `jenkins_url`, `job`, `user_id`, `stage_name`, `stage_depth`, `stage_parent`, `result` | | `jenkins.job.stage_completed` | Rate of completed stages. | `jenkins_url`, `job`, `user_id`, `stage_name`, `stage_depth`, `stage_parent`, `result` | | `jenkins.job.waiting` | Time spent waiting for job to run (in seconds). | `branch`, `jenkins_url`, `job`, `node`, `user_id` | | `jenkins.job.currently_building` | Count of currently building jobs (does not include jobs that were scheduled but have not started yet). | `jenkins_url` | | `jenkins.node.count` | Total number of node. | `jenkins_url` | | `jenkins.node.offline` | Offline nodes count. | `jenkins_url` | | `jenkins.node.online` | Online nodes count. | `jenkins_url` | | `jenkins.node_status.count` | If this node is present. | `jenkins_url`, `node_hostname`, `node_name`, `node_label` | | `jenkins.node_status.up` | If a given node is online, value 1. Otherwise, 0. | `jenkins_url`, `node_hostname`, `node_name`, `node_label` | | `jenkins.plugin.count` | Plugins count. | `jenkins_url` | | `jenkins.plugin.active` | Plugins active. | `jenkins_url` | | `jenkins.plugin.failed` | Plugins failed. | `jenkins_url` | | `jenkins.plugin.inactivate` | Plugins inactive. | `jenkins_url` | | `jenkins.plugin.withUpdate` | Plugins with update. | `jenkins_url` | | `jenkins.plugin.withWarning` | Plugins with warning. | `jenkins_url` | | `jenkins.project.count` | Project count. | `jenkins_url` | | `jenkins.queue.size` | Queue Size. | `jenkins_url` | | `jenkins.queue.buildable` | Number of Buildable item in Queue. | `jenkins_url` | | `jenkins.queue.pending` | Number of Pending item in Queue. | `jenkins_url` | | `jenkins.queue.stuck` | Number of Stuck item in Queue. | `jenkins_url` | | `jenkins.queue.blocked` | Number of Blocked item in Queue. | `jenkins_url` | | `jenkins.queue.job.in_queue` | Number of times a Job has been in a Queue. | `jenkins_url`, `job_name` | | `jenkins.queue.job.buildable` | Number of times a Job has been Buildable in a Queue. | `jenkins_url`, `job_name` | | `jenkins.queue.job.pending` | Number of times a Job has been Pending in a Queue. | `jenkins_url`, `job_name` | | `jenkins.queue.job.stuck` | Number of times a Job has been Stuck in a Queue. | `jenkins_url`, `job_name` | | `jenkins.queue.job.blocked` | Number of times a Job has been Blocked in a Queue. | `jenkins_url`, `job_name` | | `jenkins.scm.checkout` | Rate of SCM checkouts. | `branch`, `jenkins_url`, `job`, `node`, `user_id` | | `jenkins.user.access_denied` | Rate of users failing to authenticate. | `jenkins_url`, `user_id` | | `jenkins.user.authenticated` | Rate of users authenticating. | `jenkins_url`, `user_id` | | `jenkins.user.logout` | Rate of users logging out. | `jenkins_url`, `user_id` | #### Log Collection for Agents{% #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: ```yaml logs_enabled: true ``` 1. To collect Jenkins logs, create a [custom log source file](https://docs.datadoghq.com/agent/logs/?tab=tcpudp#custom-log-collection) for your Agent by creating a `conf.yaml` inside `conf.d/jenkins.d` with the following: ```yaml logs: - type: tcp port: service: source: jenkins ``` 1. In Jenkins, submit the port you specified above as the `Log Collection Port`. You can set this using environment variables, a Groovy script, or the Jenkins UI. 1. [Restart the Agent](https://docs.datadoghq.com/agent/guide/agent-commands/#start-stop-and-restart-the-agent). ### Service checks{% #service-checks %} Build status `jenkins.job.status` with the default tags: : `jenkins_url`, `job`, `node`, `user_id` ## Troubleshooting{% #troubleshooting %} ### Generating a diagnostic flare.{% #generating-a-diagnostic-flare %} Plugin diagnostic flare contains data that can be used to diagnose problems with the plugin. At the time of this writing the flare includes the following: - plugin configuration in XML format - plugin connectivity checks results - runtime data (current versions of JVM, Jenkins Core, plugin) - recent exceptions that happened inside the plugin code - plugin logs with level `INFO` and above, and recent Jenkins controller logs - current stacks of the threads of the Jenkins controller process - environment variables starting with `DD_` or `DATADOG_` (except API key and/or APP key) To generate a flare go to the `Manage Jenkins` page, find the `Troubleshooting` section, and select `Datadog`. Click on `Download Diagnostic Flare` (requires "MANAGE" permissions) to generate the flare. ## Issue tracking{% #issue-tracking %} GitHub's built-in issue tracking system is used to track all issues relating to this plugin: [jenkinsci/datadog-plugin/issues](https://github.com/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](https://issues.jenkins-ci.org/issues/?jql=project%20%3D%20JENKINS%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20component%20%3D%20datadog-plugin%20ORDER%20BY%20updated%20DESC%2C%20priority%20DESC%2C%20created%20ASC) for those issue postings. **Note**: [Unresolved issues on JIRA mentioning Datadog](https://issues.jenkins-ci.org/issues/?jql=status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%2C%20Verified%2C%20Untriaged%2C%20%22Fix%20Prepared%22%29%20AND%20text%20~%20%22datadog%22). ## Changes{% #changes %} See the [CHANGELOG.md](https://github.com/jenkinsci/datadog-plugin/blob/master/CHANGELOG.md). ## How to contribute code{% #how-to-contribute-code %} First of all and most importantly, **thank you** for sharing. Checkout the [contributing guidelines](https://github.com/jenkinsci/datadog-plugin/blob/master/CONTRIBUTING.md) before you submit an issue or a pull request. Checkout the [development document](https://github.com/jenkinsci/datadog-plugin/blob/master/DEVELOPMENT.md) for tips on spinning up a quick development environment locally.