Archival Notice

❗Notice: This project has been archived as is and is no longer actively maintained.

The current recommendation is to utilize the OpenTelemetry Plugin for Jenkins and New Relic Deployment Notifier Plugin instead.

For more details please see:

• https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/jenkins/monitoring-jenkins-ot/
• https://docs.newrelic.com/docs/change-tracking/ci-cd/change-tracking-jenkins/>
• OpenTelemetry Plugin for Jenkins
• New Relic Deployment Notifier Plugin

---

New Relic Jenkins Plugin

The New Relic Jenkins Plugin is a Jenkins plugin that provides various mechanisms for reporting information from your Jenkins server to New Relic.

The following integrations are supported.

1. Application build events (initialized, started, finalized, etc) with various build metrics reported as custom attributes are automatically pushed into Insights using the Insights Insert API.
2. APM deployment markers can be pushed to New Relic using the "Record New Relic Deployment Marker" notifier by adding a post-build step.
3. Application deployment events that mirror the APM deployment markers can be pushed into Insights whenever a deployment marker is sent using the "Create Insights Deployment Event" check box on the "Record New Relic Deployment Marker" notifier.

Installation

To install the New Relic Jenkins plugin, perform the following steps.

1. Build the New Relic Jenkins Plugin .hpi file or download the latest plugin release
2. Login to your Jenkins server as an adminstrator
3. Navigate to /jenkins/pluginManager/advanced
4. Locate the section labeled "Upload Plugin"
5. Click on the button labeled "Choose File"
6. Navigate to the New Relic Jenkins Plugin .hpi file and select it
7. Click on the button labeled "Upload"
8. Restart Jenkins

Usage

1. Register an Insights Event API insert key ^{New Relic}
2. Install the plugin ^Jenkins
3. Setup the required credentials ^Jenkins
4. Setup the proxy configuration (optional) ^Jenkins
5. Customize collection intervals (optional) ^Jenkins
6. Create custom dashboards! ^{New Relic}

Setup credentials

The Jenkins Credentials plugin is required to store the New Relic API keys used by the New Relic Jenkins plugin. To setup the required credentials, perform the following steps.

1. Login to your Jenkins server as an adminstrator
2. Navigate to /jenkins/credentials/store/system/domain/_/
3. Locate the section labeled "Upload Plugin"
4. Click on the button labeled "Add Credentials"
5. Ensure that "Username with password" is selected from the "Kind" dropdown menu
6. Ensure "Global (...)" is selected from the "Scope" dropdown menu
7. Enter your RPM account ID in the "Username" field
8. Enter your Insights Insert API Key in the "Password" field
9. Enter a value for the "ID" field, e.g. "insights-insert-key"
10. Optionally enter a value for the "Description" field.
11. Click on the button labeled "OK"
12. Navigate to /jenkins/configure
13. Scroll down to the section labeled "New Relic"
14. Select the key you just created in the dropdown labeled "Insights Insert Credentials"
15. Click on the button labeled "Save"

Setup proxy

The New Relic Jenkins Plugin supports the use of the global Jenkins Proxy Configuration for allowing Jenkins installations behind proxies to send data to New Relic. To setup the proxy configuration, perform the following steps.

1. Login to your Jenkins server as an adminstrator
2. Navigate to /jenkins/pluginManager/advanced
3. Locate the section labeled "HTTP Proxy Configuration"
4. Enter the host name of your proxy server in the field labeled "Server"
5. Enter the port of your proxy server in the field labeled "Port"
6. If your proxy server requires HTTP Proxy Authentication:
   1. Enter the proxy server username in the "User name" field
   2. Enter the proxy server password in the "Password" field
7. Optionally enter host name patterns for connections that should not go through the proxy in the field labeled "No Proxy Host", one per line.
8. Click on the button labeled "Submit"

Setup collection intervals

The New Relic Jenkins Plugin has two customizable collection intervals. The event harvest interval controls the frequency at which events are harvested from the event collector and sent to New Relic. The default is 60 seconds. The system metric sample interval controls the frequency at which samples are taken of the Jenkins environment. The default is 15 seconds.

To customize the collection intervals, perform the following steps.

1. Login to your Jenkins server as an adminstrator
2. Navigate to /jenkins/configure
3. Scroll down to the section labeled "New Relic"
4. Optionally enter a new value for the event harvest interval in the field labeled "Event Harvest Interval"
5. Optionally enter a new value for the system metric sample interval in the field labeled "System Metric Sample Interval"
6. Click on the button labeled "Save"

Dashboards

Once installed and configured, the New Relic Jenkins Plugin will immediately start sending build events for all builds in Jenkins to Insights. Build events are collected and reported to Insights in 1 minute harvest cycles by default. Insights dashboards can use the custom event type AppBuildEvent in NRQL queries to display Jenkins build data.

AppBuildEvent

Each application build event is represented by a custom Insights event of type AppBuildEvent. AppBuildEvents have the following attributes.

Attribute name	Attribute description	Example value(s)
provider	Name of the CI/CD provider	Jenkins
providerVersion	Version of the CI/CD provider	2.140
buildId	The numeric build ID of the build	65
buildUrl	The relative URL of the build	job/my%20job/65
buildName	The short name of the build	#65
buildFullName	The full "display name of the build	my job #65
buildEventType	One of initialized, started, completed, finalized	started
buildQueueId	The numeric queue ID on which the build runs	10
buildMessage	A human readable string for the build event	Completed build "my job #65" for job "my job"
buildResult	One of SUCCESS, FAILURE	SUCCESS
buildScheduled	Time the build was scheduled to start	April 19, 2019 16:48
buildStarted	Time the build was actually started	April 19, 2019 16:49
buildStartDelay	The delay between the build scheduled and start time, if any, in milliseconds	0
buildDuration	The total duration, in milliseconds, of the build	2,748
buildStatusSummary	The Jenkins build status	"broken since this build", "back to normal"
buildAgentName	Name of the node where the build ran	master
buildAgentDesc	Description of the node where the build ran	master
buildAgentLabels	The labels of the node where the build ran, separated by "|"	master|docker|macos
buildAgentHost	The host name or IP of the node where the build ran	master|docker|macos
jobUrl	The relative URL of the Jenkins job for the build	job/my%20job/
jobName	The short name of the Jenkins job for the build	my job
jobFullName	The full "display" name of the Jenkins job for the build	My Job
jenkinsMasterLabels	The node labels of the Jenkins master node, separated by "|"	master|docker|macos
jenkinsMasterHost	The host name or IP of the Jenkins master node	master-jenkins.myco.com

In addition to the attributes above, each job supports sending custom attributes with the AppBuildEvent as well as a switch to disable events for the job from being reported via the "Customize New Relic build event settings".

AppDeploymentEvent

AppDeploymentEvents can be created simultaneously with APM deployment markers by selecting the "Create Insights Deployment Event" check box on the "Record New Relic Deployment Marker" notifier when creating a post-build step. AppDeploymentEvents have the following attributes.

Attribute name	Attribute description	Example value(s)
provider	Name of the CI/CD provider	Jenkins
providerVersion	Version of the CI/CD provider	2.140
appId	The APM application ID	2536781
revision	The revision string for the deployment marker	prod-master-13.3
changelog	The change log string for the deployment marker	Added bug fix for #14
description	The description string for the deployment marker	The build for prod-master-13.3
user	The user string for the deployment marker	beeker@muppetmaster.com
jenkinsMasterLabels	The node labels of the Jenkins master node, separated by "|"	master|docker|macos
jenkinsMasterHost	The host name or IP of the Jenkins master node	master-jenkins.myco.com

JenkinsSystemEvent

Various attributes about the Jenkins environment are reported as a custom Insights event of type JenkinsSystemEvent. JenkinsSystemEvents are collected and reported to Insights in 15 second harvest cycles by default. JenkinsSystemEvents have the following attributes.

Attribute name	Attribute description	Example value(s)
provider	Name of the CI/CD provider	Jenkins
providerVersion	Version of the CI/CD provider	2.140
jenkinsMasterLabels	The node labels of the Jenkins master node, separated by "|"	master|docker|macos
jenkinsMasterHost	The host name or IP of the Jenkins master node	master-jenkins.myco.com
executorCount	The total number of executors on all nodes	10
executorsInUse	The total number of executors in use across all nodes	5
executorsFree	The total number of executors free across all nodes	5
nodeCount	The total number of nodes in the Jenkins environment (controller + agents)	2
nodesOnline	The total number of nodes online in the Jenkins environment	2
nodesOffline	The total number of nodes offline in the Jenkins environment	0
queueSize	The total number of items in the queue in any stage	5
queueItemCount	An alias for queueSize	5
queueItemsWaiting	The number of items that have entered the queue but are in their quiet period	2
queueItemsBlocked	The number of blocked items in the queue	3
queueItemsBuildable	The total number of buildable items in the queue including those that are pending	5
queueItemsPending	The number of buildable items in the queue that have been assigned to an executor	4
queueItemsStuck	The number of items that have been in the queue too long	0
queueItemsLeft	The total number of items that have left the queue including those that were cancelled	3
queueItemsCompleted	The number of items that left the queue because they were completed	2
queueItemsCancelled	The number of items that left the queue because they were cancelled	1
inQuietDownMode	Whether or not Jenkins is quieting down	false
agentConnectedCount	The total number of Jenkins Computers that are online and accepting tasks	2

Note that the the number of items that have left the queue (either via normal termination or being cancelled) is not a strictly cumulative number. The number of left items is cleared periodically because not all items can be kept indefinitely.

Example NRQL queries

Below are some sample NRQL queries that can be used to visualize build event information.

Build count billboard

SELECT uniqueCount(buildId) AS Builds, filter(uniqueCount(buildId), WHERE buildEventType='finalized' AND buildResult ='SUCCESS') AS 'Passed', filter(uniqueCount(buildId), WHERE buildEventType='finalized' AND buildResult != 'SUCCESS')  AS 'Failed' FROM AppBuildEvent SINCE TODAY

Build results timeseries

SELECT filter(uniqueCount(buildId), WHERE buildEventType='finalized' AND buildResult ='SUCCESS') AS 'Passed', filter(uniqueCount(buildId), WHERE buildEventType='finalized' AND buildResult != 'SUCCESS')  AS 'Failed' FROM AppBuildEvent TIMESERIES

Build count by job bar chart

SELECT uniqueCount(buildId) AS Builds FROM AppBuildEvent FACET jobName

Average build duration timeseries

SELECT average(buildDuration), max(buildDuration), min(buildDuration) FROM AppBuildEvent TIMESERIES

Average build duration by job bar chart

SELECT average(buildDuration) FROM AppBuildEvent FACET jobName

Average build duration by job timeseries

SELECT average(buildDuration) FROM AppBuildEvent FACET jobName TIMESERIES

Today's builds vs yesterday's builds timeseries

SELECT uniqueCount(buildId) AS Builds FROM AppBuildEvent SINCE TODAY COMPARE WITH 1 DAY AGO TIMESERIES

Average build delay timeseries

SELECT average(buildDelay) FROM AppBuildEvent

Build message event stream

SELECT buildMessage FROM AppBuildEvent LIMIT 50

Troubleshooting

To troubleshoot issues, the first steps is creating a new Jenkins logger to view the New Relic Jenkins logs. This is accomplished as follows.

1. Login to your Jenkins server as an adminstrator
2. Navigate to /jenkins/log
3. Click on the button labeled "Add new log recorder"
4. In the field labeled "Name", enter "New Relic Logger"
5. Click on the button labeled "OK"
6. Click on the button labeled "Add" next to the label "Loggers"
7. In the field labeled "Logger", enter "com.newrelic.experts"
8. Select the value "ALL" from the menu labeled "Log level"
9. Click on the button labeled "Save"

Once this logger has been created, logs can be viewed as follows.

1. Login to your Jenkins server as an adminstrator
2. Navigate to /jenkins/log
3. Click on the link labeled "New Relic Logger"
4. This page will refresh every 30s to display detailed logging output for the New Relic Jenkins plugin

Build

As with most Jenkins plugins, this plugin uses Maven to build.

1. Clone this repository
2. Run mvn package

The Jenkins HPI file will be built and placed into the target directory, e.g. [project-root]/newrelic-jenkins-plugin.hpi

Privacy Disclaimer

The New Relic Jenkins plugin collects and sends data from your Jenkins servers to the New Relic service. Pursuant to section 1.8 of the New Relic Terms & Conditions,

You shall not process or submit to the Services any Customer Data that could be legally considered sensitive in any applicable jurisdiction.

Please refer to section 1.8 of the New Relic Terms & Conditions for more information.

Contributing

Full details are available in our CONTRIBUTING.md file.

We'd love to get your contributions to improve AWS Lambda OpenTracing Java SDK! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project.

To execute our corporate CLA, which is required if your contribution is on behalf of a company, or if you have any questions, please drop us an email at open-source@newrelic.com.

Licensing

The New Relic Jenkins Plugin is licensed under the Apache 2.0 License.

The New Relic Jenkins Plugin also uses source code from third party libraries. Full details on which libraries are used and the terms under which they are licensed can be found in the third party notices document.