Deploying an app can be a risky event—when your app breaks, a bad deployment is often the cause. New Relic allows you to track deployments so you can correlate deploy to your app's performance. Tracking deployments creates deployment markers that appear in APM charts.
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, retrieve a list of past deployments, and delete past deployments on your APM application. 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. You can view deployments in the UI:
Deployment markers are not available for browser applications, but 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, get a list of past deployments, and delete 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, view, and delete deployments with the API Explorer.
JSON uses double quotes " for element names and content. Using single quotes ' will cause errors.
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.
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 @{'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):
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:
curl -X GET "https://api.newrelic.com/v2/applications/$APP_ID/deployments.json" \
-H "Api-Key:$API_KEY" \
-i
This example requests a list of deployments for app ID 9999999:
curl -X GET "https://api.newrelic.com/v2/applications/9999999/deployments.json" \
To delete a deployment, send a DELETE request that includes your API key to the deployments endpoint. DELETE requests do not use a JSON payload, but you must specify the ID for the deployment you want to delete. To retrieve the ID for a deployment, use the GET request.
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: