Track changes using NerdGraph

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 via our NerdGraph API.

For general information on using NerdGraph, see Introduction to NerdGraph.

Prerequisites

NerdGraph requirements
User permissions: Any user type can use NerdGraph to create change events and deployment markers, but only full platform users can access the curated change tracking UI experiences

Use change tracking events to monitor any modification to your system, including deployments, feature flags, business events, operational changes, or custom activities.

This method offers several benefits:

Flexible data: Add custom attributes, categories, and types to your events.
Broad visibility: You get a unified view of changes across all your accounts.
Easy to use: You don't need to know an entity.guid. This feature is powered by New Relic's flexible entity search.

To create an event, use the changeTrackingCreateEvent NerdGraph mutation. The events are stored in NRDB as changeTrackingEvent event type.

Argument	Datatype	Required?	Description
`category`	String	Yes	Categorize changes using various category and type combinations. You can either use our predefined standard categories and types or define your own custom ones. To use our standard categories and types: If you set `category` to `Deployment`: You must set the `categoryFields` argument to `Deployment`. This `deployment` argument must include a `version`. If you set `category` to `Feature Flag`: You must set the `categoryFields` argument to `FeatureFlag`. This `featureFlag` argument must include a `featureFlagId`. To use Custom categories or types: Within the `dataHandlingRules` argument, set the `validationFlags` field to `ALLOW_CUSTOM_CATEGORY_OR_TYPE`.
`dataHandlingRules`	Array of String	No	The `dataHandlingRules` field, , which includes the `validationFlags` subfield, defines how the API handles validation failures. The `validationFlags` field accepts an array of the following values: `ALLOW_CUSTOM_CATEGORY_OR_TYPE`: Required for custom or non-standard `category` and `type` combinations. Without this flag, New Relic returns an error if values don't exactly match predefined standards. For example, pairing the standard category `Deployment` with a custom type like `Rainbow` requires this flag. `FAIL_ON_FIELD_LENGTH`: Validates that string fields don't exceed 4096 characters. If a field exceeds this limit, New Relic returns an error and doesn't save the data; otherwise, the data is trimmed and appended with ellipses `(...)`. `FAIL_ON_REST_API_FAILURES`: For APM entities, the agent calls the legacy New Relic v2 REST API. If the call fails, New Relic returns an error and doesn't save the data. If this flag is omitted, New Relic returns the failure message but doesn't block the save.
`entitySearch.query`	String	Yes	Find a specific entity within New Relic. You can search by using its specific entity guid using the `id` field or by providing other identifying information if the entity guid is unknown. An entity guid is a unique identifier that New Relic assigns to your system components such as applications or microservices during their instrumentation or setup. For more information about entities, refer to New Relic Entities. Query specific entities: You can search for an exact or fuzzy matching on various attributes, including `id` and `name`, but your query must be specific enough to resolve to exactly one entity. Supported operators: The `=`, `AND`, `IN`, and `LIKE` operators are supported for entity search queries. Using special characters: Special characters such as `(`, `.` `,`, `;`, `:`, `*`,`-`, `_`, and `)` are treated as whitespace in the query string. For example, a query like `name LIKE ':aws:'` will match entity names containing `-aws` or `foo.aws`. Tags: You can reference tags with or without backticks. You can filter entities based on default entity properties and tags. Default entity properties: `id` `accountId` `name` `domainId` `alertSeverity` `reporting` `indexedAt` `firstIndexedAt` `lastReportingChangeAt` Tags: Tags are metadata typically linked to a more specific domain type or group of domain types. For example: `language`: Specifies the agent language for APM applications `clusterAgentId`: For Browser applications, this tag links to the associated APM application's cluster agent. `aws.accountId`: The `AWS account ID` for infrastructure entities monitored from AWS. Examples: To find an entity by its entity guid: `"id = '<entity guid>'"` To find an entity using its REST v2 API application ID: `"domainId = '<app id>' AND domain = 'APM'"` To find an OpenTelemetry service in a specific account: `"name = '<service name>' AND domain = 'EXT' AND type = 'SERVICE' AND accountId = '<account id>'"`
`featureFlagId`	String	No	If you select `Feature Flag` as your category, under the `categoryFields` argument, you must also select `featureFlag` and include a `featureFlagId`. This `featureFlagId` can be any string you would like to identify your feature flag by.
`type`	String	Yes	The `type` argument provides a further distinction for a change event and is used in conjunction with the `category`. For example, if an event's `category` is `Deployment`, its type might be `Rolling`. You can use a predefined standard `type` typically associated with a standard `category` or define a custom `type`. If you define a custom type, you must also: Configure the `dataHandlingRules` argument. Set the `validationFlags` field to `ALLOW_CUSTOM_CATEGORY_OR_TYPE`.
`version`	String	No	If the `category` argument is set to `Deployment`, then within the `categoryFields`, you must define `deployment` and ensure this `deployment` argument includes a `version`.
`changelog`	String	No	If the `category` is set to `Deployment`, then you can optionally include `changelog` information.
`commit`	String	No	If the `category` is set to `Deployment`, then you can optionally include `commit` information such as a commit SHA.
`deepLink`	String	No	If the `category` is set to `Deployment`, then you can optionally include `deepLink` such as a URL.
`description`	String	No	A description for the change tracking event. For example: `A change event to track the marketing campaign impact.`
`groupId`	String	No	A `groupId` attribute lets you organize the related changes across one or more entities. By using the same `groupId` for each related change, you can easily view these changes together in New Relic interfaces or refine query results. You can also use the same `groupId` to add changes to an existing group. TIP New Relic recommends using the `groupId` attribute when making multiple updates to one or more entities or implementing various changes across your system.
`shortDescription`	String	No	A short description for each change lets you identify the change events sent to New Relic quickly. If left blank, an autogenerated description is created that includes the entity, user, and version. The short description appears in the following areas: In the marker flag as a tool tip, when you hover over a change marker on the chart. In the Activity stream panels.
`user`	String	No	User identification or a valid email address. For example, user: `datanerd@example.com`.

You can define your custom attributes as key-value pairs to add additional metadata to change events.

Parameters	Datatype	Description
`customAttributes`	Object	A `customAttributes` field is specified as `key-value` pairs in JavaScript object format, where values can be of `string`, `boolean`, or `number` types. JavaScript numbers are stored as Java `long` or `double` values. Unlike `JSON`, keys in JavaScript objects are not quoted. To add a custom attribute, structure it as follows: `customAttributes: {keyName : "value", anotherKeyName: 2.1}`

Parameters

Datatype

Description

customAttributes

Object

A customAttributes field is specified as key-value pairs in JavaScript object format, where values can be of string, boolean, or number types. JavaScript numbers are stored as Java long or double values. Unlike JSON, keys in JavaScript objects are not quoted. To add a custom attribute, structure it as follows:

customAttributes: {keyName : "value", anotherKeyName: 2.1}

To prevent naming conflicts with default attribute names and NRQL keywords, the following custom attribute names are restricted:

accountId
ago
and
appID
as
auto
begin
begintime
category
categoryType
changeTrackingId
compare
customAttributes
customType
day
days
description
end
endtime
entity.domain
entity.guid
entity.name
entity.type
entityGuid
entityName
explain
eventType
facet
from
fb.input
groupId
hostname
hour
hours
in
is
like
limit
log
minute
minutes
month
months
not
null
offset
or
plugin.type
raw
second
seconds
select
since
timeseries
timestamp
type
until
user
week
weeks
where
with

New Relic automatically sets the timestamp and changeTrackingId attributes. You can provide the timestamp value as long as it is within one day before or after the current time. However, the changeTrackingId must be unique and will always be generated by New Relic.

Parameters	Datatype	Description
`changeTrackingId`	String	The `changeTrackingId` is a unique identifier generated when a change is recorded. You can use this ID in NerdGraph and NRQL queries to identify specific changes. For example: `changeTrackingId = '8a3a594c-e726-4bc2-8078-26dffec9a3d8'`.
timestamp	`EpochMilliseconds`	The `timestamp` attribute shows when a NerdGraph call was received. You can provide it by specifying the number of milliseconds since the Unix epoch. For example: `timestamp: 1032480000000`. Importante Timestamps must be applied within +/- 24 hours of the current time when the NerdGraph call is made, or the payload will be rejected.

Sample mutations

The following examples show NerdGraph mutations, with their required and optional attributes, for creating tracking markers:

mutation {
  changeTrackingCreateEvent(
    changeTrackingEvent: {
      categoryAndTypeData: {
        categoryFields: { deployment: { version: "1234" } }
        kind: { category: "deployment", type: "basic" }
      }
      entitySearch: { query: "id = 'ENTER YOUR ENTITY GUID HERE'" }
    }
  ) {
    changeTrackingEvent {
      category
      categoryAndType
      changeTrackingId
      customAttributes
      description
      entity {
        name
        guid
      }
      groupId
      shortDescription
      timestamp
      user
      type
    }
    messages
  }
}

mutation {
  changeTrackingCreateEvent(
    changeTrackingEvent: {
      categoryAndTypeData: {
        kind: { category: "BUSINESS_EVENT", type: "CONVENTION" }
      }
      user: "testUser"
      shortDescription: "sample activity event description"
      description: "sample event description"
      groupId: "testGroup123"
      customAttributes: {
        isProduction: true
        region: "us-east-1"
        instances: 2
        deployTimeMs: 10.5
      }
      entitySearch: { query: "id = 'YOUR ENTITY GUID HERE'" }
    }
  ) {
    changeTrackingEvent {
      category
      categoryAndType
      changeTrackingId
      customAttributes
      description
      entity {
        name
        guid
      }
      groupId
      shortDescription
      timestamp
      user
      type
    }
    messages
  }
}

mutation {
  changeTrackingCreateEvent(
    changeTrackingEvent: {
      categoryAndTypeData: {
        kind: { category: "External Event", type: "Cloud Provider Outage" }
      }
      user: "product@example.com"
      description: "Cloud Provider outage for US-East for Production customer database"
      entitySearch: { query: "id = 'YOUR ENTITY GUID HERE'" }
    }
    dataHandlingRules: { validationFlags: [ALLOW_CUSTOM_CATEGORY_OR_TYPE] }
  ) {
    changeTrackingEvent {
      category
      categoryAndType
      changeTrackingId
      customAttributes
      description
      entity {
        name
        guid
      }
      groupId
      shortDescription
      timestamp
      user
      type
    }
    messages
  }
}

Use case examples for change tracking events

Here are example GraphQL mutations for creating change tracking events:

mutation {
  changeTrackingCreateEvent(
    changeTrackingEvent: {
      categoryAndTypeData: {
        categoryFields: { deployment: { version: "1.2.3" } }
        kind: { category: "deployment", type: "basic" }
      }
      entitySearch: { query: "id = 'YOUR ENTITY GUID HERE'" }
    }
  ) {
    changeTrackingEvent {
      category
      categoryAndType
      changeTrackingId
      customAttributes
      description
      entity {
        name
        guid
      }
      groupId
      shortDescription
      timestamp
      user
      type
    }
    messages
  }
}

mutation {
  changeTrackingCreateEvent(
    changeTrackingEvent: {
      categoryAndTypeData: {
        kind: { category: "BUSINESS_EVENT", type: "MARKETING_CAMPAIGN" }
      }
      user: "marketing@example.com"
      shortDescription: "Black Friday campaign launch"
      description: "Launched Black Friday marketing campaign with 30% discount"
      groupId: "blackfriday2024"
      customAttributes: {
        campaignType: "seasonal"
        discountPercent: 30
        targetAudience: "premium_customers"
      }
      entitySearch: { query: "name = 'ecommerce-app' AND domain = 'APM'" }
    }
  ) {
    changeTrackingEvent {
      category
      categoryAndType
      changeTrackingId
      customAttributes
      description
      entity {
        name
        guid
      }
      groupId
      shortDescription
      timestamp
      user
      type
    }
    messages
  }
}

mutation {
  changeTrackingCreateEvent(
    changeTrackingEvent: {
      categoryAndTypeData: {
        categoryFields: { featureFlag: { featureFlagId: "new-checkout-flow" } }
        kind: { category: "FEATURE_FLAG", type: "BASIC" }
      }
      user: "product@example.com"
      shortDescription: "Enabled new checkout flow"
      description: "Rolled out new streamlined checkout process to 25% of users"
      entitySearch: { query: "id = 'YOUR ENTITY GUID HERE'" }
    }
  ) {
    changeTrackingEvent {
      category
      categoryAndType
      changeTrackingId
      customAttributes
      description
      entity {
        name
        guid
      }
      groupId
      shortDescription
      timestamp
      user
      type
    }
    messages
  }
}

Standard categories and types

For change tracking events, these are the valid predefined category and type pairs:

Category	Type
`Deployment`	`Basic` `Blue Green` `Canary` `Rolling` `Shadow`
`Deployment Lifecycle`	`Artifact Copy` `Artifact Deletion` `Artifact Deployment` `Artifact Move` `Build Deletion` `Build Promotion` `Build Upload` `Image Deletion` `Image Promotion` `Image Push` `Release Bundle Creation` `Release Bundle Deletion` `Release Bundle Sign`
`Feature Flag`	`Basic`
`Business Event`	`Convention` `Marketing Campaign` `Other`
`Operational`	`Crash` `Other` `Scheduled Maintenance Period` `Server Reboot`

Change tracking deployments provide specialized tracking for code deployments and infrastructure changes. This is the legacy method that focuses specifically on deployment events. You can create deployment markers using the changeTrackingCreateDeployment mutation. These markers are stored in NRDB as Deployment event type.

Sugerencia

New Relic recommends migrating to change tracking events using changeTrackingCreateEvent for better flexibility and feature support. Deployment markers will continue to work but have limited functionality compared to change events.

To track a change, such as a deployment, you must set the following:

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

Argument

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

Sugerencia

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.

Argument	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"`.
`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"`.
`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`.
`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). Sugerencia 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`. Importante 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"`.

Deployment mutation examples

The examples below show how to create deployment markers using the legacy API:

mutation {
  changeTrackingCreateDeployment(
    deployment: {
      version: "0.0.1"
      user: "INSERT_YOUR_NAME"
      timestamp: INSERT_MS_EPOCH_TIMESTAMP
      groupId: "78641"
      entityGuid: "INSERT_YOUR_GUID"
      description: "create a new marker"
      deploymentType: BASIC
      deepLink: "example.com/path"
      commit: "INSERT_A_COMMIT_HASH"
      changelog: "test log"
    }
  ) {
    changelog
    commit
    deepLink
    deploymentId
    deploymentType
    description
    entityGuid
    groupId
    timestamp
    user
    version
  }
}

What's next

View and analyze changes

Learn advanced techniques for correlating change data with performance metrics and system behavior.

Query your changes

Learn how to query your change data in New Relic.

Notify your team

Learn how to set up notifications for your change tracking events.

Prerequisites

Argument

TIP

Custom attributes

Auto-generated attributes

Importante

Sample mutations

Mutation with only required fields

Mutation with optional fields

Mutation with validation flag for custom category or type

Use case examples for change tracking events

Simple deployment event mutation

Business event mutation with custom attributes

Feature flag event mutation

Standard categories and types

standard-categories-types

Sugerencia

Required arguments

Sugerencia

Optional arguments

Sugerencia

Attributes set by New Relic

Importante

Deployment mutation examples

Mutation with only required fields

Mutation with optional fields

What's next

View and analyze changes

Query your changes

Notify your team

Track changes using NerdGraph

Prerequisites .css-21sua1{background:none;border:none;width:0;padding:0;}

Custom attributes

Auto-generated attributes

Sample mutations

Mutation with only required fields

Mutation with optional fields

Mutation with validation flag for custom category or type

Use case examples for change tracking events

Simple deployment event mutation

Business event mutation with custom attributes

Feature flag event mutation

Standard categories and types

standard-categories-types

Sugerencia

Required arguments

Optional arguments

Attributes set by New Relic

Deployment mutation examples

Mutation with only required fields

Mutation with optional fields

What's next

View and analyze changes

Query your changes

Notify your team

Prerequisites