• English日本語한국어
  • Log inStart now

Track changes using Jenkins

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:

  1. 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.

  2. Open Jenkins, and click Manage Jenkins.

    Screenshot showing where to find Manage Jenkins
  3. Click Manage Plugins.

    Screenshot showing where to find Manage Plugins
  4. Click Advanced.

    Screenshot showing the Advanced button in Jenkins
  5. Under Deploy Plugin, click Choose File and upload the file newrelic-deployment-notifier.hpi.

  6. 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:

  1. Click Installed.

    Screenshot of the Installed tab in Jenkins
  2. 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.

    Screenshot showing the rollback button
  3. 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.

  1. Go to the pipeline tab, and at the bottom, click Pipeline Syntax:

    Screenshot showing the Pipeline Syntax option
  2. Click the Sample Step dropdown and select step: General Build Step.

    Screenshot showing how to find the Sample Step dropdown
  3. Under Build Step, select New Relic Deployment Notifications.

    Screenshot showing how to find Deployment Notifications
  4. 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."

  5. Click Generate Pipeline Script.

  6. Copy the script, return to the main pipeline page, and paste it into the pipeline script.

    Screenshot showing an example of pasting into Pipeline tab
  7. 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.

Copyright © 2023 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.