Record and view deployments

Important

We recommend that you use the change tracking feature instead of the older deployment markers. If you've been using deployment markers feature, you can still use it, but keep in mind that the change tracking feature is available for browser and mobile, as well as APM.

Deploying an app can be a risky event—when your app breaks, and a bad deployment is often the cause. New Relic allows you to track deployments so you can correlate deployments with changes in your app's performance. Tracking deployments creates deployment markers that appear in APM charts and dashboards.

See how deployment markers work in this short video (4:30 minutes):

Options for tracking deployments

You can use the New Relic REST API v2 to record new deployments and retrieve a list of past deployments. In addition, some APM agents have agent-specific methods to record deployments automatically.

You can use your Slack integration with New Relic, or a simple webhook, to notify your team in real time of deployments for applications monitored by APM. Slack provides a webhook URL that allows you to post generic JSON that will appear formatted in a chosen Slack channel.

There are a few places where you can view deployments in the New Relic UI after they have been recorded:

In the activity feed on the APM Summary, Service summary, and entity summary pages.
On APM performance charts as chart markers (vertical lines with pinheads).
On dashboard charts as chart markers.
On the Deployments page for summary performance.

Tip

Deployment markers are not available for browser applications yet, but we will be releasing a new API soon that does support that. Contact us through this sign-up form to learn more about participating in a limited preview. Also, see browser releases for a way to tag errors with release versions.

Record deployments with the REST API

You can use the New Relic REST API v2 to record deployments and get a list of past deployments.

The examples in this document use curl as a command line tool. However, you can use any method to make your REST requests. You can also create and view deployments with the API Explorer.
JSON uses double quotes " for element names and content. Using single quotes ' will cause errors.
The examples use X-Api-Key which can be used for either a user key or a REST API key. User keys are now the preferred way of accessing our REST APIs, and you may use Api-Key headers when using them.

To record a new deployment, send a POST request that includes your API key to the deployments endpoint. Attach the payload in JSON format (see Character limits and JSON parameters). All payload parameters are optional except revision.

For example:

bash

$curl -X POST "https://api.newrelic.com/v2/applications/$APP_ID/deployments.json" \
>     -H "X-Api-Key:$API_KEY" \
>     -i \
>     -H "Content-Type: application/json" \
>     -d \
>'{
$    "deployment": {
$        "revision": "REVISION",
$        "changelog": "Added: /v2/deployments.rb, Removed: None",
$        "description": "Added a deployments resource to the v2 API",
$        "user": "datanerd@example.com",
$        "timestamp": "2019-10-08T00:15:36Z"
$    }
$}'

To record a deployment with PowerShell, send a POST request that includes your API key to the deployments endpoint. Attach the payload in JSON format (see Character limits and JSON parameters). All payload parameters are optional except revision.

This example uses PowerShell version 3 or higher:

Invoke-WebRequest -Uri https://api.newrelic.com/v2/applications/YOUR_APP_ID/deployments.json -Method POST -Headers @{'X-Api-Key'='$API_KEY'} -ContentType 'application/json' -Body '{
    "deployment": {
        "revision": "REVISION",
        "changelog": "Added: /v2/deployments.rb, Removed: None",
        "description": "Added a deployments resource to the v2 API",
        "user": "datanerd@example.com",
        "timestamp": "2019-10-08T00:15:36Z"
    }
}'

This example uses PowerShell version 2 (requires .NET framework 3.5 or higher):

$encoding = [System.Text.Encoding]::GetEncoding("ASCII")
$data ='{
    "deployment": {
        "revision": "REVISION",
        "changelog": "Added: /v2/deployments.rb, Removed: None",
        "description": "Added a deployments resource to the v2 API",
        "user": "datanerd@example.com",
        "timestamp": "2019-10-08T00:15:36Z"
    }
}'
$postData = $encoding.GetBytes($data)
$request = [System.Net.WebRequest]::Create('https://api.newrelic.com/v2/applications/$APP_ID/deployments.json')
$request.Method = 'POST'
$request.Headers.add('X-Api-Key','$API_KEY')
$request.ContentType='application/json'
$stream = $request.GetRequestStream()
$stream.Write($postData,0,$postData.Length)
$request.GetResponse()

To retrieve a list of all past deployments for your app, send a GET request that includes your API key to the deployments endpoint. GET requests do not use a JSON payload.

For example:

bash

$curl -X GET "https://api.newrelic.com/v2/applications/$APP_ID/deployments.json" \
>     -H "X-Api-Key:$API_KEY" \
>     -i

This example requests a list of deployments for app ID 9999999:

bash

$curl -X GET "https://api.newrelic.com/v2/applications/9999999/deployments.json" \
>     -H "X-Api-Key:ABCDEFGHIJKLMNOPQRSTUVWXabcdefghijklmnopqrstuvwx" \
>     -i

The API returns this list of deployments:

HTTP/1.1 200 OK
ETag: "ABCDEFGHIJKabcdefghijk0123456789"
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json
{
  "deployments": [
    {
      "id": 1234567,
      "revision": "1234123412341234123412341234123412341234",
      "changelog": "Fixed the bugs for real this time",
      "description": "Example description two",
      "user": "Data Nerd",
      "timestamp": "2016-02-24T10:09:27-08:00",
      "links": {
        "application": 9999999
      }
    },
    {
      "id": 2345678,
      "revision": "7890789078907890789078907890789078907890",
      "changelog": "Think I fixed all the bugs",
      "description": null,
      "user": "Dren Atad",
      "timestamp": "2014-10-22T12:23:47-07:00",
      "links": {
        "application": 9999999
      }
    }
  ],
  "links": {
    "deployment.agent": "/v2/applications/{application_id}"
  }
}

The JSON payload can include the following parameters.

Important

UTF-8 4 byte characters, such as Emojis and some non-Latin language glyphs, cannot be used in the deployment text.

Parameter	Data type	Description
`revision`	String, 127 character maximum	Required. A unique ID for this deployment, visible in the Summary page and on the Deployments page. Can be any string, but is usually a version number or a Git checksum.
`changelog`	String, 65535 character maximum	Optional. A summary of what changed in this deployment, visible in the Deployments page when you select (selected deployment) > Change log.
`description`	String, 65535 character maximum	Optional. A high-level description of this deployment, visible in the Summary page and on the Deployments page when you select an individual deployment.
`user`	String, 31 character maximum	Optional. A username to associate with the deployment, visible in the Summary page and on the Deployments page.
`timestamp`	ISO 8601	Optional. When the deployment occurred, down to the second. If not specified, the deployment will be recorded at the time when the API call was received. Timestamp requirements: Must be in UTC time. Must be after the most recent deployment timestamp. Cannot be in the future. Must be in ISO8601 format; for example, `"2019-10-08T00:15:36Z"`.

Record deployments using the New Relic agent

Some agents have additional methods to record deployments:

All agents: Use the New Relic REST API v2.
C: No SDK-specific methods. Use the REST API.
Go: No agent-specific methods. Use the REST API.
Java: Call the Java agent jar.
.NET: Use PowerShell and the REST API.
Node.js: No agent-specific methods. Use the REST API.
PHP: Use a PHP script.
Python: Use the record-deploy subcommand of the newrelic-admin script.
Ruby: Use a Capistrano recipe.

Notify your team about deployments

After a deployment is recorded, through either the REST API or the newer GraphQL API, you can notify your team members using a webhook.

You can send deployment data to a variety of webhook destinations. Simply follow the instructions for whatever tool you're using—except Slack. If you want to use a Slack webhook, you must use the legacy New Relic Alerts app instead of the New Relic Slack app like this:

Log in to your Slack account as an admin, and then go to Apps.
Search for New Relic Alerts, and click on that tile when it appears.
In the New Relic Alerts listing, click the Configuration button below the New Relic icon.
Click the Configuration tab below the heading New Relic Alerts.
On the Configuration tab, click the pencil icon.
Scroll down to the Webhook URL section, and click Copy URL.
Go to one.newrelic.com > (user menu) > Administration > Integrations > Deploy notifications.
Paste the Slack webhook URL into Webhook URL.
Click Integrate with webhooks.

View deployment details

Important

This section and the next are about how to use the current deployment markers UI. If you see a blue banner in the UI about being in a limited preview, you have access to the the new UI. In this case, switch to these new instructions.

After you configure the deployment information, you can view and drill down into details:

Go to one.newrelic.com > All capabilities > APM & services > (select an app) > Events > Deployments.
Use any of New Relic's standard user interface functions to drill down into detailed information.
To view details for a particular event, select its date link.
To view the errors page for this deployment, select the error link.
To view details for a specific deployment if applicable, select Change log or Change report.

The Change log contains any detail provided through the changelog parameter when recording the deployment. The Change report displays the behavior of the top ten transactions before and after the deployment.

View performance after a deployment

The Deployments page link for individual deployments appears on the selected app's Summary page in the Events section. For time frames shorter than 14 days, a blue vertical bar on a chart will indicate a deployment. To view summary information about the deployment, mouse over the blue bar.

Tip

You can also use the Compare with option on your APM summary page to select a time period to compare the same data. If you enable Compare with, the UI does not show deployment markers.

Important

Options for tracking deployments

Tip

Record deployments with the REST API

Record a deployment with POST

Record a deployment with PowerShell

View a list of deployments with GET

Sample output from GET

Character limits and JSON parameters

Important

Record deployments using the New Relic agent

Notify your team about deployments

View deployment details

Important

View performance after a deployment

Tip