From c9d8eacb96d17d186a5131234b57275b8e9339c1 Mon Sep 17 00:00:00 2001 From: WriteMayur Date: Mon, 15 Sep 2025 01:37:31 +0530 Subject: [PATCH 01/15] GA changes for change tracking --- .../change-tracking-graphql.mdx | 330 ------- .../change-tracking-introduction.mdx | 95 -- .../change-tracking-view-analyze.mdx | 1 + .../change-tracking-webhooks.mdx | 2 + .../ci-cd/change-tracking-github-actions.mdx | 349 ------- .../{ => config}/change-tracking-events.mdx | 8 +- .../change-tracking-jenkins.mdx | 2 + .../cli.mdx} | 2 + .../change-tracking/config/github-actions.mdx | 357 +++++++ .../docs/change-tracking/config/nerdgraph.mdx | 929 ++++++++++++++++++ src/content/docs/change-tracking/overview.mdx | 204 ++++ .../docs/change-tracking/query-data.mdx | 6 + src/nav/change-tracking.yml | 59 +- 13 files changed, 1547 insertions(+), 797 deletions(-) delete mode 100644 src/content/docs/change-tracking/change-tracking-graphql.mdx delete mode 100644 src/content/docs/change-tracking/change-tracking-introduction.mdx delete mode 100644 src/content/docs/change-tracking/ci-cd/change-tracking-github-actions.mdx rename src/content/docs/change-tracking/{ => config}/change-tracking-events.mdx (98%) rename src/content/docs/change-tracking/{ci-cd => config}/change-tracking-jenkins.mdx (99%) rename src/content/docs/change-tracking/{change-tracking-cli.mdx => config/cli.mdx} (98%) create mode 100644 src/content/docs/change-tracking/config/github-actions.mdx create mode 100644 src/content/docs/change-tracking/config/nerdgraph.mdx create mode 100644 src/content/docs/change-tracking/overview.mdx create mode 100644 src/content/docs/change-tracking/query-data.mdx diff --git a/src/content/docs/change-tracking/change-tracking-graphql.mdx b/src/content/docs/change-tracking/change-tracking-graphql.mdx deleted file mode 100644 index 8f15613c4c0..00000000000 --- a/src/content/docs/change-tracking/change-tracking-graphql.mdx +++ /dev/null @@ -1,330 +0,0 @@ ---- -title: 'Track changes using NerdGraph (GraphQL)' -tags: - - APM - - APM UI pages - - Events - - Browser - - Mobile - - NerdGraph -metaDescription: "Here's how to use NerdGraph (GraphQL) to designate what you want to capture with change tracking." -freshnessValidatedDate: never ---- - -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. - -For general information on using NerdGraph, see [Introduction to NerdGraph](/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph). - -## Requirements [#api-requirements] - -Requirements include: - -* [NerdGraph requirements](/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/#authentication) -* User permissions: Any [user type](/docs/accounts/accounts-billing/new-relic-one-user-management/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 [#field-definitions] - -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](/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic/#find). -
- `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](#jenkins-markers) 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: - - ```graphql - { - 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 [#mutation-examples] - -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: - - - - ```graphql - mutation { - changeTrackingCreateDeployment( - deployment: { - version: "0.0.1", - entityGuid: "INSERT_YOUR_GUID" - } - ) - { - deploymentId - entityGuid - } - } - ``` - - - - ```graphql - 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 [#whats-next] - -After you've used mutations to designate the changes you want to track, you can analyze the effect of those changes in the New Relic UI: - -* Query your changes: You can write your own GraphQL or NRQL queries to see details about changes you're tracking. For details, see [Query change data](/docs/change-tracking/change-tracking-view-analyze/#query-deployments). -* Use our curated charts: For details, see [How to view and analyze your changes in New Relic](/docs/change-tracking/change-tracking-view-analyze). diff --git a/src/content/docs/change-tracking/change-tracking-introduction.mdx b/src/content/docs/change-tracking/change-tracking-introduction.mdx deleted file mode 100644 index 51b7e3bf33f..00000000000 --- a/src/content/docs/change-tracking/change-tracking-introduction.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: 'Capture and analyze changes in your systems' -tags: - - APM - - APM UI pages - - Events - - Browser - - Mobile -metaDescription: "Here's an overview of how the change tracking feature can help you analyze the effects of recent changes on your users and systems." -redirects: - - /docs/apm/agents/php-agent/features/recording-deployments-using-php-script - - /docs/agents/php-agent/features/recording-deployments-using-php-script -freshnessValidatedDate: never ---- - -Change tracking allows you to capture changes, such as deployments, on any part of your system and use them to contextualize performance data. With this feature, you can: - -* Record changes via API or configure your deployment pipelines to do it for you. -* View those changes as markers on charts for APM, browser, , service level management, custom dashboards, and many more experiences across New Relic. - -Our change analysis UIs provide details and insights about each of the changes you track, such as faceted errors, log attribute trends, related issues and anomalies, and calculated impacts on key signals. With these insights, you'll be able to understand the impact of changes on system performance and quality. Change tracking metadata, such as commit SHAs, changelogs, and deep links, will help you resolve issues more quickly. - -To get acquainted with various aspects of change tracking, watch the video below or see our [feature highlights](#feature-highlights). If you're ready to capture and analyze changes across your stack, see [Start tracking changes](#start-tracking). - -