We're still working on this feature, but we'd love for you to try it out!
This feature is currently provided as part of a preview pursuant to our pre-release policies.
The Change Tracking capability lets you capture, visualize, and analyze changes across your applications and infrastructure. This feature is designed to help you understand how changes impact both your system and your customer.
Capture all changes impacting your system: Send change events for any type of change, including feature flags changes, configuration changes, and business events. You can also create custom change events tailored to your specific requirements. Use the changeTrackingCreateEvent NerdGraph mutation to easily send various types of change events.
Gain a comprehensive view to manage system-wide changes: Seamlessly view and filter change events across all of your entities and accounts from one unified interface. Effortlessly identify changes by filtering by team, type, custom attributes, and any other criteria.
Quickly correlate changes with telemetry to accelerate root cause discovery: Enhance your understanding of change impact by visualizing change events alongside your time-series data. To find the root cause faster, add a time-series query to display change events with relevant metrics, allowing for clear correlation.
Enrich your change events with comprehensive metadata: Track all the necessary information about your changes using custom attributes, categories, and types. Tailor your change events to include all specifics needed for thorough system clarity.
Access the Change Tracking page in New Relic
You can access the Change Tracking page in the following ways:
The Change Tracking across all entities page displays a consolidated view of change events for all accounts and entities on one page. It enables you to:
Review changes across all accessible accounts and entities.
Filter change events by account, entity, deployment type, and other attributes to refine results.
Add a timeseries query to visualize change events against timeseries data across various entities and accounts.
To add the Change Tracking page to your left navigation, click the pin icon.
The Change Tracking across all entities page displays the change events for all entities and accounts for which you have access. You can view these events in the two components:
Change events table: This table lists change events from your accessible accounts. Each event in the table is also marked on the time-series chart.
To refine the list, use the filter bar with event attributes and entity tags.
Adjust the displayed time range using the time picker, or by clicking and dragging a selection directly on the chart.
Change events time-series chart: Run a NRQL query and view the results on this chart with change events overlaid. This visualization helps you correlate data trends (such as spikes or dips) with specific system changes across your accounts.
TIP
The chart and table can each display a maximum of 1,000 events. If your current filters and time range result in more than 1,000 events, only the 1,000 most recent events are shown. To view a more specific set of events (fewer than 1,000), apply a more restrictive filter or select a shorter time range.
Change Tracking entity-scoped view
The entity-scoped Change Tracking view displays change events for a specific entity, such as APM, browser, or mobile. It also offers additional information related to golden signals for each change event.
To access the Change Tracking for entity-scoped view:
Select the required entity then click Change Tracking.
Track changes using NerdGraph
The New Relic change tracking capability allows you to monitor the impact of various modifications on your systems. For instance, you can record a marketing campaign as a change event and then use the Change Tracking UI to analyze its effect on system performance through charts.
To record deployments and other types of change events, use the NerdGraph mutation changeTrackingCreateEvent. For more information about using NerdGraph, refer to Introduction to NerdGraph.
All types of New Relic users can use NerdGraph to create change events, but only full platform users can access the curated change tracking UI experiences.
Change tracking event mutation
Use the changeTrackingCreateEvent mutation to create a change event by providing its required and optional attributes.
Important
Change events created using the changeTrackingCreateEvent mutation are not currently displayed in the APM Summary Deployments tile and the Transaction 360 feature during its public preview. These events are planned to appear in both upon GA.
Attributes
Datatype
Description
category
String
A category attribute allows you to categorize changes using various categories and types. You can either use our predefined standard categories and types or define your own custom ones.
You must set the categoryFields attribute to Deployment.
This deployment field must include a version.
If you set category to Feature flag:
You must set the categoryFields attribute to Feature flag.
This featureFlag field must include a featureFlagId.
To use Custom categories:
Within the dataHandlingRules attribute, set the validationFlags field to ALLOW_CUSTOM_CATEGORY_OR_TYPE.
type
String
The type attribute provides a further distinction for a change event, often 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 attribute.
Set the validationFlags attribute to ALLOW_CUSTOM_CATEGORY_OR_TYPE.
version
String
If the category attribute is set to Deployment, then within the categoryFields attribute, you must define a deployment field and ensure this deployment field includes a version.
featureFlagId
String
If you select Feature flag as your category, under the categoryFields attribute, you must also select featureFlag and include a featureFlagId. This id can be any string you would like to identify your feature flag by.
dataHandlingRules
String
When you define a custom category, type, or a non-standard combination of category and type, you must configure the dataHandlingRules attribute. This action is coupled with setting the validationFlags attribute to ALLOW_CUSTOM_CATEGORY_OR_TYPE.
If validationFlags is not set to ALLOW_CUSTOM_CATEGORY_OR_TYPE when using such custom or non-standard values, New Relic will return an error if a category or type value does not exactly match a predefined standard value. For example, even if you use a standard category such as Deployment, pairing it with a custom type such as Rainbow which is not a New Relic standard combination requires you to set validationFlags to ALLOW_CUSTOM_CATEGORY_OR_TYPE and configure dataHandlingRules.
Conseil
When validationFlags is set to ALLOW_CUSTOM_CATEGORY_OR_TYPE, ensure that the string values you provide for your custom category or type attributes use the exact casing that you intend to see in the New Relic UI.
entitySearchquery
String
The entity search attributes enables you to find a specific entity within New Relic. You can search by using its specific entity GUID or by providing other identifying information if the entityGuid is unknown. An entityGuid 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 are supported operators 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 domainType or group of domainTypes. 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 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: "name = '<service name>' AND domain = 'EXT' AND type = 'SERVICE' AND accountId = '<account id>'"
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.
Parameters
Datatype
Description
description
String
A description for the change tracking event. For example: A change event to track the marketing campaign impact.
groupId
String
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
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
User identification or a valid email address. For example, user: datanerd@example.com.
changelog
String
If the category is set to Deployment, then you can optionally include changelog information.
commit
String
If the category is set to Deployment, then you can optionally include commit information such as a commit SHA.
deepLink
String
If the category is set to Deployment, then you can optionally include deepLink such as a URL.
New Relic automatically sets the timestamp and changeTrackingId attributes. You can modify the timestamp value. however, the changeTrackingId must be unique and is always generated by New Relic.
Parameters
Datatype
Description
timestamp
EpochMilliseconds
The timestamp attribute shows when a NerdGraph call was received. You can modify it by specifying the number of milliseconds since the Unix epoch. For example: timestamp: 1032480000000.
Important
Timestamps must applied within +/- 24 hours of the current time when the NerdGraph call is made, or the payload will be rejected.
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".
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: {key_name : "value_name"}
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
Sample mutations
The following examples show NerdGraph mutations, with their required and optional attributes, for creating tracking markers:
The Detail page provides similar functionality for non-deployment changes as it does for deployment-type changes. For more information, refer View and analyze your changes.
Query change events using NRQL
You can query change events using NRQL and NerdGraph to analyze and visualize changes. Here are some example queries you can use:
Purpose
NRQL/NerdGraph
Query
To get change events for last week
NRQL
SELECT*FROM ChangeTrackingEvent SINCE 1 week ago
To compare transaction errors to change markers for an application for the last month
NRQL
SELECTcount(*)
FROM TransactionError
WHERE appName ='INSERT_YOUR_APP_NAME'AND http.statusCode >300
SINCE 1month ago TIMESERIES
To list a set of events across all accounts for the past hour
NerdGraph
{
actor{
changeTracking{
changeTrackingSearch{
changeEvents{
shortDescription
category
type
changeTrackingId
customAttributes
description
groupId
timestamp
type
user
}
}
}
}
}
To filter change event data by timeWindow, accountIds, and entity guid query
