The change tracking feature allows you to track the effect of various changes on your customers and systems. For example, if you make some deployments, you can use the change tracking feature to monitor the results in New Relic UI charts. You'll also get access to features that help you understand the effects of those changes.
Instead of designating which changes you want to monitor by using our CLI or a CI/CD integration, you can do the same thing using GraphQL mutations and queries via our NerdGraph API.
User permissions: Any user type can use NerdGraph to create deployment markers and track other changes, but only full platform users can access the curated change tracking UI experiences.
Understand fields in NerdGraph explorer
The fields you'll use in your GraphQL queries fall into these general types:
To track a change, such as a deployment, you must set the following:
Attribute
Description
entityGuid
The entityGuid value is the unique identifier assigned by New Relic to your system components during instrumentation and setup processes. For more information on New Relic Entities and finding Entity GUIDs, see this guide.
version
The version attribute value can be anything, although we recommend using the version number set during your build process. To see an example of how this can be done, see our Jenkins deployments plugin documentation below. If you already report version numbers to New Relic or by some other means, we recommend using the same here to set yourself up for forthcoming features that will allow you to facet and correlate data by version.
ヒント
If you are transitioning away from the legacy REST API, you'll need to start using your application's entity GUID instead of the appID. You can easily find the GUID in NerdGraph with this query:
{
actor{
entitySearch(query:"domainId=INSERT_YOUR_APPID"){
count
query
results{
entities{
entityType
name
guid
}
}
}
}
}
You can define some optional and useful attributes to add context to the change you are tracking. These attributes can also enable certain change tracking features.
Attribute
Description
changelog
You can submit a URL or any string for the changelog attribute. For example: changelog: "Added: /v2/deployments.rb, Removed: None" or changelog: "https://github.com/nodejs/node/blob/v4.2.3/CHANGELOG.md".
description
You can submit any string for the description attribute. For example: description: "Added a deployments resource to the v2 API".
The description attribute may be where you choose to insert codified information from your internal deployment management processes. You can use IDs or tags you assign to each commit or deployment that describes organizational or business aspect of the work, for example, EU_MAINT_DMARK_v101.
commit
You can submit any string for the commit attribute, and we suggest using the commit SHA associated with the deployment or change, for example, commit: "r3ws4sa43f".
deepLink
You can submit any URL for the deepLink attribute. We suggest using one that will help someone evaluating a change on New Relic to quickly get to a place where they can take further action, such as Jenkins, ArgoCD, or GitHub Actions. Here's an example: deepLink: "http://localhost:8080/job/PipelineV2/configure".
deploymentType
You can divide changes related to deployments into different types. These types align with common deployment techniques, but there is also an OTHER type. Types include:
BASIC
BLUE_GREEN
CANARY
ROLLING
SHADOW
OTHER
Assigning a type to each deployment will help you filter results on change tracking interfaces and NerdGraph/NRQL query results.
groupId
You may want to group deployments in cases where you're making a series of changes to one or more entities or releasing many changes across many entities within your system. By setting the same groupId attribute value for each related deployment, you can more easily see these changes together in New Relic interfaces or use the groupId to narrow query results.
The groupId can be any string of your choosing, and you can continue to add deployments to a group after the first use of the groupId (in case you want to relate this deployment to one that happened weeks or even months ago).
ヒント
In addition to using the groupId to relate many deployments, you may also use the attribute to define long-running changes. For example, two deployments with the same groupId could bracket a period during which alerts were suppressed or some migration was taking place.
user
Can be any string, for example, user: "datanerd@example.com".
New Relic automatically sets the timestamp and deploymentId attributes. You can provide a timestamp value as an override, but deploymentId will always be generated by New Relic to ensure uniqueness.
Attribute
Description
timestamp
The time at which the NerdGraph call was received. You can provide an override here as the number of milliseconds since the Unix epoch. For example: timestamp: 1032480000000.
重要
There is a firm limitation applied that all timestamps must be +/- 24 hours of the current time when the NerdGraph call is received or the payload will be rejected.
deploymentId
A unique identifier generated when the deployment is recorded. While you cannot set deploymentId, you can use it in your NerdGraph and NRQL queries to locate specific deployments. Here's an example: deploymentId: "8a3a594c-e726-4bc2-8078-26dffec9a3d8".
Create a change tracking marker using a mutation
To record a change, such as a deployment, you'll need to include the required fields, and then decide if you want to include any optional fields.
Here are some example GraphQL mutations that show some ways to create deployment markers: