diff --git a/src/content/docs/apis/nerdgraph/examples/nerdgraph-metric-normalization-rule.mdx b/src/content/docs/apis/nerdgraph/examples/nerdgraph-metric-normalization-rule.mdx new file mode 100644 index 00000000000..13b1e1382b8 --- /dev/null +++ b/src/content/docs/apis/nerdgraph/examples/nerdgraph-metric-normalization-rule.mdx @@ -0,0 +1,346 @@ +--- +title: "NerdGraph tutorial: Managing the Metric Normalization Rules" +metaDescription: "Learn how to manage metric normalization rules using NerdGraph." +freshnessValidatedDate: never +--- + + + 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 program pursuant to our [pre-release policies](/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy). + + + +The [NerdGraph API explorer](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/) is a powerful tool designed to manage metric normalization rules for your applications. By leveraging NerdGraph mutations, you can create, edit, enable, and disable these rules directly from your New Relic account. This provides a streamlined and programmatic approach to resolve Metric Grouping Issues (MGIs). + +Metric Grouping Issues arise when an application generates an excessive number of unique metrics, often from web transaction metrics named from URLs. This high cardinality can lead to performance degradation and make it difficult to analyze and monitor application performance effectively. Metric normalization rules offer a solution by grouping or filtering out metric timeslice data, thereby reducing high cardinality and preventing metric grouping issues. + +The NerdGraph API Explorer acts as a single-pane-of-glass interface to manage all your metric normalization rules across multiple applications or instances. This centralized and flexible solution ensures consistency and significantly reduces the effort required to maintain these rules. + + +## Requirements [#review-requirements] + +* You need a [New Relic account](https://newrelic.com/signup), and with that account, you can access your API user key that you need to include with [queries and mutations]((https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/#terminology)). + +* User type and assigned roles can affect your NerdGraph permissions. For more details, see [Factors affecting access](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/factors-affecting-access-features-data/#user-permissions). + + +## Mutations [#nerdgraph-mutations] + +Manage your metric normalization rules with the following [NerdGraph mutations](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/#terminology): + + + + + + + +Use `metricNormalizationCreateRule` mutation creates a new metric normalization rule in New Relic. This rule helps to manage the high cardinality metrics by renaming, dropping, or transforming them before they are ingested to New Relic. This helps in addressing the MGI and ensuring that your metrics are well-organized and meaningful. + +### Input parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Attribute nameData typeDescription
accountIdString(Required) The account ID associated with the rule.
action String (Required) From the drop-down list select the required action: + - `REPLACE`: Replace the `matchExpression` metrics with value defined in the `replacement`. + - `IGNORE`: Block any metrics that match the `matchExpression` from reporting to New Relic. + - `DENY_NEW_METRICS`: Prevent the creation of new metric names that match the matchExpression, but allow existing metric names to continue reporting. +
applicationGuidString(Optional) The unique GUID for the application in New Relic. If left blank, this becomes an account-wide rule.
enabledBoolean(Required) If set to `true` to enable the rule.
evalOrderInteger(Required) Specify the order in which the rule is applied relative to other rules. Lower the numbers, higher the evaluated priority. Recommend value is `2000`
matchExpressionString(Required) Accepts [regex](https://regexone.com/) pattern that matches the metrics to be normalized. This field always starts with a `^` and ends with a `$`. It defines the pattern for identifying which metrics should be affected by the normalization rule. For example: + ```^WebTransaction/Uri/RESTfulExample/users/username/[a-zA-Z0-9]+$``` + The pattern `^[a-zA-Z0-9]+$` matches any string made up of lowercase characters `(a-z)`, uppercase characters `(A-Z)`, and numbers `(0-9)`.
notesStringAdditional notes or comments about the normalization rule.
replacementStringThis field is only required when from the `action` drop-down list `REPLACE` option has selected. It replaces any metric name matched via the `matchExpression`. For example: `WebTransaction/Uri/RESTfulExample/users/username/{username}$`
terminateChainBoolean(Required) If set to `true`, no further rules will be applied once this rule matches a metric.
+ +### Sample query + +```graphql + + mutation { + metricNormalizationCreateRule( + rule: {action: IGNORE, applicationGuid: "", enabled: false, matchExpression: "^WebTransaction/Uri/RESTfulExample/users/username/[a-zA-Z0-9]+$", notes: "", terminateChain: false, replacement: "WebTransaction/Uri/RESTfulExample/users/username/{username}", evalOrder: 2000} + accountId: 0 + ) + } + +``` + + +### Response parameters + +Once the rule has been created, the response will have an additional a `ruleId` parameter. You can use the `ruleId` parameter to manage the rule. + +```graphql + +query response for create rule + +``` + +### Sample response + + +```graphql + +query response for create rule + +``` + + + + + + + Use the `metricNormalizationEditRule` mutation to update the value of existing existing rule using the `ruleId` parameters. It provides a flexibility to adjust the rule as per the new insights or changing requirements. + +### Input parameters + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Attribute nameData typeDescription
accountIdString(Required) The account ID associated with the rule.
actionString(Required) From the drop-down list select the required action: + - `REPLACE`: Replace the `matchExpression` metrics with value defined in the `replacement`. + - `IGNORE`: Block any metrics that match the `matchExpression` from reporting to New Relic. + - `DENY_NEW_METRICS`: Prevent the creation of new metric names that match the matchExpression, but allow existing metric names to continue reporting. +
applicationGuidString(Optional) The unique GUID for the application in New Relic. If left blank, this becomes an account-wide rule.
enabledBoolean(Required) If set to `true` to enable the rule.
evalOrderInteger(Required) Specify the order in which the rule is applied relative to other rules. Lower the numbers, higher the evaluated priority. Recommend value is `2000`
idString(Required) The `ruleId` of the metric rule for which you want to update the value.
matchExpressionString(Required) Accepts [regex](https://regexone.com/) pattern that matches the metrics to be normalized. This field always starts with a `^` and ends with a `$`. It defines the pattern for identifying which metrics should be affected by the normalization rule. For example: + ```^WebTransaction/Uri/RESTfulExample/users/username/[a-zA-Z0-9]+$``` + The pattern `^[a-zA-Z0-9]+$` matches any string made up of lowercase characters (a-z), uppercase characters (A-Z), and numbers (0-9).
notesStringAdditional notes or comments about the normalization rule.
replacementStringThis field is only required when from the `action` drop-down list `REPLACE` option is selected. It replaces any metric name matched via the `matchExpression`. For example: `WebTransaction/Uri/RESTfulExample/users/username/{username}$`
terminateChainBoolean(Required) If `true`, no further rules will apply once this rule matches a metric.
+ +### Sample query + +```graphql + +graphql query for edit rule + +``` + +### Response Parameters + +```graphql + +query response + +``` + +### Sample Response + + `Example response ` + + + + + + + Use the `metricNormalizationEnableRule` mutation to enable a previously disabled rule using the `accountId` and `ruleId` parameters + +### Input Parameters + + + + + + + + + + + + + + + + + + + + + +
Attribute nameData typeDescription
accountIdString(Required) The account ID associated with the rule.
ruleIdString(Required) The `ruleId` of the metric rule.
+ +### Example query + +```graphql + +mutation { + metricNormalizationEnableRule(accountId: test, ruleId: test) +} + +``` + +### Response Parameters + +`response` + + +### Sample response + + + + + + + + + The `metricNormalizationDisableRule` mutation to disables a previously enabled rule using the `accountId` and `ruleId` parameters. + + +### Input Parameters + + + + + + + + + + + + + + + + + + + + + +
Attribute nameData typeDescription
accountIdString(Required) The account ID associated with the rule.
ruleIdString(Required) The `ruleId` of the metric rule.
+ +### Example query + +```graphql + +mutation { + metricNormalizationDisableRule(accountId: test, ruleId: test) +} + +``` + +### Response Parameters + +```response``` + + +### Sample response + +```sample response``` + + + + \ No newline at end of file diff --git a/src/nav/telemetry-data-platform.yml b/src/nav/telemetry-data-platform.yml index 304f9e7c731..01fb5ce5ed4 100644 --- a/src/nav/telemetry-data-platform.yml +++ b/src/nav/telemetry-data-platform.yml @@ -199,6 +199,8 @@ pages: path: /docs/apis/nerdgraph/examples/nerdgraph-slm - title: Synthetic monitoring tutorial path: /docs/apis/nerdgraph/examples/nerdgraph-synthetics-tutorial + - title: Metric normalization rules tutorial + path: /docs/apis/nerdgraph/examples/nerdgraph-metric-normalization-rule - title: REST APIs pages: - title: REST API v2