The change tracking feature allows you to designate changes you want to monitor to see how they affect your customers and systems.
While you can designate which changes you want to monitor by using GraphQL or our CLI, you can also record changes using pipelines in Jenkins.
A pipeline will call whatever build you specify and also pass additional environment variables to the build process. This populates the data that is needed for your deployment to show up in charts across New Relic. You'll see the results in the change tracking UIs, and you can use this information to understand the impact of changes on entity health.
Before you get started make sure you're using Jenkins version 2.222.4 or greater.
Manage the plugin
To record changes you want to track, you need a special plugin, which you can easily add or remove from your Jenkins instance.
Complete the following steps as a Jenkins administrator.
Add the plugin
Important
The plugin installation steps below require a restart of Jenkins.
To add the plugin:
Download the plugin from here, and if the filename is changed during download, rename the file to
newrelic-deployment-notifier.hpi
.Tip
Note that this is a temporary download location for the plugin. We'll let you know when you can download this directly in Jenkins.Open Jenkins, and click Manage Jenkins.
Click Manage Plugins.
Click Advanced.
Under Deploy Plugin, click Choose File and upload the file
newrelic-deployment-notifier.hpi
.To finish the installation, make sure no jobs are running, and then restart Jenkins. You can also check the box Restart Jenkins when installation is complete and no jobs are running:
Remove the Plugin
To remove the plugin using Plugin Manager:
Click Installed.
Roll it back to the previous version by entering deploy in the search box, selecting New Relic Deployment Notifier Plugin, and then clicking the rollback symbol.
You can also uninstall it by clicking the X icon.
Create and run the pipeline
Follow these steps to create a pipeline script that will pass your deployment details to Jenkins when it runs your build. A Jenkins pipeline is a list of steps that are chained together. You can create a Jenkins pipeline in one of two ways:
- Create a
Jenkinsfile
and put it at the root of a source code repository - Use the pipeline script functionality of Jenkins
Each stage consists of a list of steps, and one of the steps in this part (likely the very last one) is to call the NewRelicDeploymentNotifier
to put a marker for a successful build.
The plugin we've created takes the GUID as a parameter. You can identify the GUID as a variable in the Environment
section and use it as a variable in subsequent steps. The build is called by putting it in a stage and list of steps.
Go to the pipeline tab, and at the bottom, click Pipeline Syntax:
Click the Sample Step dropdown and select step: General Build Step.
Under Build Step, select New Relic Deployment Notifications.
Complete the following fields (we've included the REST API fields for people not using the GraphQL API):
Field
GraphQL API
REST API
Description
API Key
Required
Required
API Credentials to conduct the deployment action in New Relic. Credentials can be created by creating new credentials in Jenkins using a username and password. Specify any identifier for the username, and the API key for the password.
applicationID
N/A
Required
This is only used for calls to the REST API. Do not include this if you're creating a call to the GraphQL endpoint.
Description
Optional
Optional
Insert a description of what you are tracking.
Revision
N/A
Required
Revision for the deployment.
Changelog
Optional
Optional
Reference to the list of changes incurred in the deployment.
Commit
Optional
N/A
A hash to reference the commit ID.
Deeplink
Optional
N/A
A deep link to either the Jenkins job or any other reference to the deployment.
EntityGuid
Required
N/A
The application entity in reference to the deployment (see More about the application GUID).
DeploymentType
Optional
N/A
The type of deployment that is being conducted.
GroupId
Optional
N/A
An identifier to reference a cluster of changes.
Timestamp
Optional
N/A
Optional timestamp in Unix Epoch long format. If not provided, then we will set it to the time we received the request, which will be the number of milliseconds since the Unix Epoch.
Version
Required
N/A
Required field for the version of what's being deployed.
User
Optional
Optional
The user conducting the deployment. This is a free-form field. In Jenkins, we recommend you specify either the name on the commit or something like "Jenkins auto deploy."
Click Generate Pipeline Script.
Copy the script, return to the main pipeline page, and paste it into the pipeline script.
Execute the pipeline script to create your deployment marker in New Relic.
Tip
If you want to still send requests to the New Relic REST API, you can drop the EntityGuid
and add applicationID
.
Move this pipeline script to GitHub
You can store pipeline scripts in GitHub. To retrieve the pipeline script, you can specify the location of the GitHub repository when creating an application in Jenkins.
More about the application GUID
Currently, GUIDs cannot be assigned dynamically to the pipeline. You must find the entity GUID in New Relic (see Learn about New Relic entities and then hardcode this value in the pipeline script to report deployment notifications for that entity. This information is not sensitive and can be stored publicly.
The credentials used to update the application should mitigate sending bad deployment markers. In addition, the credentials are referenced by ID in Jenkins, so they do not need to be stored in source code repositories.
How to detect if failures occur
Pipeline syntax errors will halt the pipeline. Pipeline parsing errors (like missing build steps) will halt the pipeline. You should troubleshoot these using Jenkins tools to construct appropriate pipeline scripts. Using the WYSIWYG Pipeline Syntax tool in Jenkins can help you appropriately construct the New Relic deployment notification.
If the plugin detects an error, it should not halt the pipeline. It will log an exception and a stack trace, and then it will continue. This helps you prevent interruptions when building and deploying applications.
What's next
After you've designated the changes you want to track, you can analyze the effect of those changes in the New Relic UI. For details, see How to view and analyze your changes in New Relic.