---
title: Introduction to change tracking
source: https://docs.newrelic.com/docs/change-tracking/overview
---

Modern applications change frequently through deployments, feature flags, configuration updates, and operational modifications. When performance issues occur, teams struggle to identify which of the recent changes caused the problem.

New Relic's change tracking captures and visualizes system modifications, helping you quickly correlate changes with performance impacts and resolve issues faster.

[Video](https://fast.wistia.net/embed/iframe/j3k8h14qjk)

Watch this two-minute video explaining change tracking.

/\*  \*/

## Why use change tracking? [#why]

Change tracking helps you answer critical questions when issues arise:

-   **"What changed before this outage?"** See a timeline of all modifications leading up to incidents
-   **"Did our deployment cause this regression?"** Compare performance metrics before and after releases
-   **"Which feature flag toggle affected conversion rates?"** Correlate business metrics with configuration changes

**Use cases:**

-   Development teams correlate deployments with performance regressions
-   Product teams analyze feature launch impact on user experience
-   SRE teams track operational changes during incidents

## Key features [#key-features]

-   **Universal change capture**: Record any modification, feature flags, business events, operational changes, and custom activities
-   **Visual correlation**: View interactive change markers overlaid on performance charts across APM, browser, mobile, and custom dashboards
-   **Any entity**: Changes can be associated with any [entity](docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic/) on the New Relic platform
-   **Advanced analysis**: Access detailed impact analysis including error trends, anomaly detection, and comparative before/after metrics
-   **Rich metadata**: Include context like commit SHAs, changelogs, user information, and custom attributes
-   **Unified data storage**: All change data stored in NRDB for consistent querying with NRQL and NerdGraph
-   **Flexible integration**: Configure via APIs, CLI, or CI/CD pipeline integrations such as GitHub Actions and Jenkins

## How you can configure change tracking? [#config]

Setting up change tracking involves understanding requirements, choosing your tracking method, configuring integration, and analyzing the data:

### Compatibility and requirements [#req]

Ensure your environment meets the requirements for change tracking:

-   **User permissions**: Any [user type](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-type) can create change events and deployment markers via NerdGraph, but only [full platform users](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-type/#user-type-capabilities) can access the curated change tracking UI experiences
-   **Entity access**: Ensure you have access to the entities (APM services, mobile apps, infrastructure hosts) where you want to track changes

### Configure change tracking [#setup]

Configure change tracking using the method that best fits your workflow:

#### Change tracking events

Track changes for any system modification including deployments, feature flags, business events such as marketing campaigns and conventions, operational changes such as server reboots and maintenance, and custom activities. It provides flexible categorization, custom attributes, unified cross-account visibility, and advanced filtering capabilities. You can also dynamically associate an event with an entity using New Relic's embedded entity search, which eliminates the need to know the `entity.guid`.

You can configure change tracking events using one of the following methods:

-   **[NerdGraph API](https://docs.newrelic.com/docs/change-tracking/config/nerdgraph#event)**: Create change events via GraphQL mutations
-   **[New Relic CLI](https://docs.newrelic.com/docs/change-tracking/config/cli#event)**: Use CLI for quick setup
-   **[GitHub Actions](https://docs.newrelic.com/docs/change-tracking/config/github-actions#event)**: Automate change events in CI/CD pipelines

#### Change tracking deployments (Legacy)

You can configure change tracking deployments using one of the following methods:

-   **[NerdGraph API](https://docs.newrelic.com/docs/change-tracking/config/nerdgraph#deployment)**: Record deployments via GraphQL mutations
-   **[New Relic CLI](https://docs.newrelic.com/docs/change-tracking/config/cli#deployment)**: Command line deployment tracking
-   **[Jenkins](https://docs.newrelic.com/docs/change-tracking/config/change-tracking-jenkins)**: Automated tracking with Jenkins plugin
-   **[GitHub Actions](https://docs.newrelic.com/docs/change-tracking/config/github-actions#deployment)**: Configure deployment tracking in workflows

### View and analyze your change data [#analyze]

After configuring change tracking, you can:

-   Access the unified interface to view all change events across entities and accounts, with filtering by team, type, custom attributes, and time correlation with metrics. For more information, refer to [view and analyze your data](https://docs.newrelic.com/docs/change-tracking/view-analyze-data).

-   Use [NRQL](https://docs.newrelic.com/docs/change-tracking/query-data#use-nrql) and [NerdGraph](https://docs.newrelic.com/docs/change-tracking/query-data#use-graphql) to build custom analysis and dashboards.

-   You can use [webhooks to send change event](https://docs.newrelic.com/docs/change-tracking/change-tracking-webhooks) notifications to your teams.

/\* 
\## Additional capabilities \[#additional-capabilities]

Change tracking offers comprehensive capabilities to help you understand the effects of changes in your systems.

\### Capture any type of change across your entire system \[#capture-range-of-changes]

Change tracking supports extensive change monitoring capabilities:

\*\*Change events\*\*: Monitor any system modification including:
\* Feature flag changes and configuration updates
\* Business events like marketing campaigns and conventions
\* Operational changes such as server reboots and maintenance periods
\* Deployment events for code releases and infrastructure updates
\* Custom events tailored to your specific requirements

\*\*Deployment tracking\*\*: A specialized approach for tracking deployments across  services, mobile apps, infrastructure hosts, workloads, and more. If you're using the old REST v2 APM deployments API, migrate to our GraphQL API to capture changes on all \[entity types](/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic/#find) and leverage \[Jenkins](/docs/change-tracking/ci-cd/change-tracking-jenkins) and \[GitHub Actions](/docs/change-tracking/ci-cd/change-tracking-github-actions) integrations.

Our goal is to provide full-platform coverage for markers on charts. While some New Relic experiences don't yet feature interactive markers on all charts, you can still record changes and build custom experiences using dashboards.

\### Unified view across all changes \[#what-changed]

Once you start \[capturing changes](#start-tracking), you'll automatically see interactive markers on related charts throughout New Relic:

\*\*For change events\*\*: Access the \[Change Tracking page](/docs/change-tracking/change-tracking-events) to view all change events across entities and accounts. Filter by team, type, custom attributes, and correlate events with time-series data for comprehensive analysis.

\*\*For deployments\*\*: Interactive markers appear on APM, mobile, browser, service level management, and custom dashboard charts. You'll also see entity sidebar options like \*\*Deployments\*\* across New Relic.

\### Lower your mean time to resolution (MTTR) \[#mttr]

Change tracking has powerful interfaces to help you quickly understand the impact a change has had on your system. Here are some tasks change tracking can help with:

\* Want to see how many regressions or new error groups we detected since a change? For more about regressions, see \[errors inbox](/docs/errors-inbox/errors-inbox/#status).
\* Want to see what anomalous activity we identified since a change?
\* Need to run a head-to-head comparison of changes to see if things are getting better or worse?

You can do these tasks (and more) with our new change tracking UIs. Read about the change tracking experience in \[How to view and analyze your changes in New Relic](/docs/change-tracking/change-tracking-view-analyze/).

\### All change data stored in one unified location \[#single-source-truth]

Every change you capture—whether change events or deployments—is stored in the New Relic database (NRDB) as structured data. You can query all change data using:

\* \*\*NRQL\*\*: Query change events and deployment markers for custom analysis
\* \*\*NerdGraph\*\*: Access change event and deployment data programmatically
\* \*\*Change Tracking UI\*\*: Use the unified interface to filter and analyze all changes

For examples of querying change data, see \[Query change data](/docs/change-tracking/change-tracking-view-analyze/#query-deployments) and \[Query change events using NRQL](/docs/change-tracking/change-tracking-events/#query-change-events-nrql).


  Data stored in NRDB is immutable and as such, the markers you create cannot be deleted. The events created will be stored for 13 months by default.


\### Rich metadata for comprehensive change context \[#api-fields]

Change tracking provides extensive metadata options to connect changes with workflows and enable effective team collaboration:

\*\*For change events\*\*: Add custom attributes, categorize by type (feature flags, business events, operational changes, deployments), include user information, and group related changes across entities using \`groupID\`.

\*\*For deployments\*\*: Include commit SHAs, changelogs, deep links to CI/CD platforms, and use \`groupID\` attributes to relate multiple deployments.

This rich metadata helps teams quickly understand change context, trace issues to specific modifications, and share relevant information without switching between tools.

\### Get the information you need without switching contexts \[#context-switching]

You can see changes on parts of your system related to the entity you're looking at without switching contexts. By leveraging the New Relic \[entity relationships feature](/docs/apis/nerdgraph/examples/nerdgraph-relationships-api-tutorial/), you can automatically see changes to related entities drawn on charts alongside changes made to the central entity. For more on entity relationships, see this \[NerdGraph tutorial](/docs/apis/nerdgraph/examples/nerdgraph-relationships-api-tutorial/). \*/

## What's next [#whats-next]

[Set up using NerdGraph](https://docs.newrelic.com/docs/change-tracking/config/nerdgraph)

Learn how to set up change tracking for your entities using NerdGraph to monitor them in New Relic.

[Set up using CLI](https://docs.newrelic.com/docs/change-tracking/config/cli)

Learn how to set up change tracking for your entities using CLI to monitor them in New Relic.

[View and analyze changes](https://docs.newrelic.com/docs/change-tracking/view-analyze-data/)

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