NerdGraph tutorial: View and configure an entity's golden metrics

Golden metrics and golden tags are bits of information about an entity that we consider to be the most important for that entity. We use this information to display a brief overview of an entity across all New Relic. You can see and contribute to the standard definitions of the golden metrics and tags in this public repository.

This document explains how to query an entity's custom metrics using NerdGraph.

Fetch golden metrics

When fetching golden metrics for a specific GUID or list of GUIDS, the provided queries are already filtered for you. You can run the resulting query as is in the query builder. The resulting metric can be either a TIMESERIES or a single value.

Here's an example of one golden metric query for an AWS DynamoDB table entity with the GUID ENTITY_GUID.

SELECT average(provider.getSuccessfulRequestLatency.Average)
FROM DatastoreSample
WHERE entityGuid IN ('ENTITY_GUID') AND provider='DynamoDbTable'
TIMESERIES

You can use NerdGraph to query for the golden metrics of a specific entity; for example:

{
  actor {
    entity(guid: "ENTITY_GUID") {
      goldenMetrics {
        metrics {
          query
          title
        }
      }
    }
  }
}

Fetch golden tags

Golden tags are always represented the same way, whether requested by guid or by entityType. You will always receive the list of tag keys considered the most important about the entity.

{
  actor {
    entity(guid: "ENTITY_GUID") {
      goldenTags {
        tags {
          key
        }
      }
    }
  }
}

Customize golden metrics and golden tags

If you want to change the golden metrics and golden tags based on the specificities of your environment, you can override them in two different contexts, in your account, or in a workload.

Override golden metrics or golden tags for a specific entity type in your whole account

In this case, the new golden metrics or the new golden tags will be applied in all of New Relic, converting your new metrics and tags as the default for the specified entity type.

To do that, you can use a NerdGraph mutation to override the golden metrics for a specific entity.

mutation {
  entityGoldenMetricsOverride(
    context: { account: ACCOUNT_TO_OVERRIDE_GOLDEN_METRICS }
    domainType: { domain: DOMAIN, type: TYPE }
    metrics: [
      {
        eventId: EVENT_ID
        select: NRDB_QUERY_SELECT
        from: NRDB_QUERY_EVENT
        where: NRDB_QUERY_WHERE
        title: TITLE_OF_THE_METRIC
        facet: FACET
        name: NAME_OF_THE_METRIC
      }
    ]
  ) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

Where:

• domainType: The entity type of the metrics to override.
• context: The context to fetch the golden metrics from. In this case, you should set the account that you want to override.
• metrics: The new NRDB query will be shown as golden metrics.
  • eventId: The field used to filter the entity in the metric. How the entity GUID is defined in your event.
  • select: The SELECT clause of the NRDB query. This field is required.
  • from: The FROM clause of the NRDB query.
  • where: Complementary WHERE clause to identify the entity type field.
  • facet: The field to FACET.
  • title: The title of the golden metric. This field is optional.
  • name: The name of the golden metric. This field is required.

mutation {
  entityGoldenMetricsOverride(
    context: { account: ACCOUNT_ID }
    domainType: { domain: "APM", type: "APPLICATION" }
    metrics: [
      {
        eventId: "entity.guid"
        from: "Transaction"
        name: "cpuUsage"
        select: "max(cpuUsage)"
        title: "CPU Usage"
      }
      {
        eventId: "guid"
        from: "Metric"
        where: "metricTimesliceName in ('HttpDispatcher', 'OtherTransaction/all')"
        facet: "appName"
        select: "count(newrelic.timeslice.value)"
        name: "throughput"
        title: "Throughput"
      }
    ]
  ) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

The metrics input object defines the parts of an NRDB query, split into sections. One of these sections is the eventId, which is used to identify the field that defines the GUID inside the NRDB Event you want to use as a golden metric. For example:

SELECT average(provider.getSuccessfulRequestLatency.Average)
FROM DatastoreSample
WHERE entityGuid IN ('EntityGuid') AND
      provider='DynamoDbTable'
FACET entityName TIMESERIES

It's defined as follows:

{
    eventId: "entityGuid",
    from: "DatastoreSample",
    where: "provider='DynamoDbTable'",
    facet: "entityName",
    select: "average(provider.getSuccessfulRequestLatency.Average)",
    name: GetItem latency (ms),
    title: GetItem latency (ms)
}

As you can see in the resultant object, the where clause only contains the provider field. The system adds the where clause with the eventId field by default.

You can do the same for the golden tags using this NerdGraph mutation:

mutation {
  entityGoldenTagsOverride(
    context: { account: ACCOUNT_ID }
    domainType: { domain: "APM", type: "APPLICATION" }
    tags: [{ key: "applicationName" }, { key: "environment" }]
  ) {
    errors {
      message
      type
    }
    tags {
      context {
        account
      }
      domainType {
        domain
        type
      }
      tags {
        key
      }
    }
  }
}

Override golden metrics from a particular entity type in a workload

New Relic's workloads provide an aggregated view of health and performance data about a group of entities. The time series charts shown for each entity type in a workload are defined by the golden metrics in the workload account.

If you want to further customize which time series to show for a specific entity type in a particular workload, override the golden metrics in the account with the following mutation:

mutation {
  entityGoldenMetricsOverride(
    context: { guid: WORKLOAD_TO_OVERRIDE_GOLDEN METRICS }
    domainType: { domain: DOMAIN, type: TYPE }
    metrics: [
      {
        eventId: EVENT_ID
        select: NRDB_QUERY_SELECT
        from: NRDB_QUERY_EVENT
        where: NRDB_QUERY_WHERE
        title: TITLE_OF_THE_METRIC
        facet: FACET
        name: NAME_OF_THE_METRIC
      }
    ]
  ) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

See above for details on each field. In this case, context is the workload's GUID.

mutation {
  entityGoldenMetricsOverride(
    context: { guid: WORKLOAD_ENTITY_GUID }
    domainType: { domain: "APM", type: "APPLICATION" }
    metrics: [
      {
        eventId: "entity.guid"
        from: "Transaction"
        name: "cpuUsage"
        select: "max(cpuUsage)"
        title: "CPU Usage"
      }
      {
        eventId: "guid"
        from: "Metric"
        where: "metricTimesliceName in ('HttpDispatcher', 'OtherTransaction/all')"
        facet: "appName"
        select: "count(newrelic.timeslice.value)"
        name: "throughput"
        title: "Throughput"
      }
    ]
  ) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

Fetch the custom golden metrics and golden tags

The queries defined in the previous sections always return the default golden metrics and golden tags. If you want to fetch your custom golden metrics or golden tags, you need to send the context defined in the query, for example:

{
  actor {
    entity(guid: INFRA_AWSDYNAMODBTABLE_GUID) {
      goldenMetrics(
        context: { account: ACCOUNT_ID, guid: WORKLOAD_ENTITY_GUID }
      ) {
        metrics {
          title
          query
          name
        }
      }
    }
  }
}

For golden tags:

{
  actor {
    entity(guid: INFRA_AWSDYNAMODBTABLE_GUID) {
      goldenTags(context: { account: ACCOUNT_ID, guid: WORKLOAD_ENTITY_GUID }) {
        tags {
          key
        }
      }
    }
  }
}

You can send both contexts simultaneously for querying, if your metrics or tags have the context inside the workload. The API returns the most specific golden metric or golden tags based on the context that you defined in the requests. The priority is workload and account.

Reset custom metrics and golden tags

If your custom golden metrics are not relevant to you any more, you can restore the defaults defined by New Relic. In the context parameter, set the desired account or workload guid (in the guid parameter).

To restore your golden metrics in an account, run this query:

mutation {
  entityGoldenMetricsReset(
    context: { guid: ACCOUNT_TO_OVERRIDE_GOLDEN_METRICS }
    domainType: { domain: DOMAIN, type: TYPE }
  ) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

Where:

• domainType: The entity type of the metrics to override.
• context: The context to fetch the golden metrics from. In this case, you should set the account you want to reset.

To restore your golden metrics in a workload, run this query:

mutation {
  entityGoldenMetricsReset(
    context: { guid: GUID_TO_OVERRIDE_GOLDEN_METRICS }
    domainType: { domain: DOMAIN, type: TYPE }
  ) {
    errors {
      message
      type
    }
    metrics {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      metrics {
        definition {
          eventId
          facet
          from
          select
          where
        }
        name
        query
        title
      }
    }
  }
}

You can do the same for your custom golden tags:

mutation {
  entityGoldenTagsReset(
    context: { guid: WORKLOAD_ENTITY_GUID }
    domainType: { domain: "APM", type: "APPLICATION" }
  ) {
    errors {
      message
      type
    }
    tags {
      context {
        account
        guid
      }
      domainType {
        domain
        type
      }
      tags {
        key
      }
    }
  }
}

Expected errors

All these mutations can answer with the result of the operation or a list of errors.

These are all the expected errors that you can receive:

• INVALID_CONTEXT: The context is not valid. There can only be one context, an account or a workload's GUID. If you use both, or use any other concept, or a GUID that doesn't belong to a workload, you will get this error.
• INVALID_DOMAIN_TYPE: The domain type is not valid.
• LIMIT_EXCEEDED: The maximum amount of metrics is 9. If you exceed this limit you will get this error.
• NOT_AUTHORIZED: The user doesn't have the permissions to carry out this action.