Record and monitor deployments

Deployments of applications can be risky events. New Relic allows you to correlate those events to the performance of your applications, using deployment markers that appear in APM charts. Several options are available to manage your deployment data.

Options

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.

After recording deployments, you can view their summary performance data in the APM Deployments page and a timeline of deployments in the Event log list on the APM Overview page.

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.

Access to this feature depends on your subscription level. Deployment markers are not available for Browser applications, but see Browser releases for a way to tag errors with release versions.

Notify your team of deployments

Owners and Admins

After a deployment is recorded using the REST API, you can optionally notify a webhook endpoint of the deployment.

The destination of the webhook can be your Slack instance. To use webhooks to set up a deployment notification for a Slack channel:

  1. Log in to your Slack account as an admin, then go to App directory > Manage > Apps.
  2. Search for your New Relic app, then select Add configuration.
  3. From Post to channel, select an existing Slack channel or add a new channel, then Add configuration.
  4. From the list of options, copy the webhook URL.
  5. Go to rpm.newrelic.com > account dropdown > Account settings > Integrations > Deploy notifications > Webhook.
  6. Paste the Slack webhook URL, then save.
  7. Optional: Send a test message.

You can also use webhooks, Slack channels, and other options for alert notifications with New Relic Alerts.

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.
Record a deployment with POST

To record a new deployment, send a POST request that includes your REST 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:

curl -X POST 'https://api.newrelic.com/v2/applications/${APP_ID}/deployments.json' \
     -H 'X-Api-Key:${APIKEY}' -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-09-01T11:00:00-08:00"
  }
}' 

To record a deployment with PowerShell, send a POST request that includes your REST 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/APP_ID/deployments.json -Method POST -Headers @{'X-Api-Key'='APIKEY'} -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-09-01T11:00:00-08:00"
}
}'

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-09-01T11:00:00-08:00"
}
}'
$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','APIKEY')
$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 REST 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 'X-Api-Key:${APIKEY}' \
    -i
Sample output from GET

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

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}"
  }
}

To delete a deployment, send a DELETE request that includes your Admin User's 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.

For example:

curl -X DELETE 'https://api.newrelic.com/v2/applications/${APP_ID}/deployments/DEPLOYMENT_ID.json' \
     -H 'X-Api-Key:${ADMIN_USERS_KEY}' \
     -i

The JSON payload can include the following parameters.

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 Overview 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 Overview 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 Overview 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 after the most recent deployment timestamp.
  • Cannot be in the future.
  • Must be in ISO8601 format; for example, "2019-09-01T11:00:00-07:00".

If a timezone is not specified, the timestamp will be interpreted in UTC.

Record deployments using the New Relic agent

Some agents have additional methods to record deployments:

End of life notification: Hipchat, Campfire

As of September 9, 2019, integrations with Hipchat and Campfire for APM deployment notifications will no longer be available. Recommendation: If you are still using Hipchat or Campfire, use webhooks with Slack channels instead. For more information, see the New Relic Explorers Hub post.

For more help

Recommendations for learning more: