• EnglishEspañol日本語한국어Português
  • Log inStart now

Rules for creating metrics: requirements and tips

Here are some limits, requirements, and recommendations when you create metrics from events, logs, or spans.

Metric aggregation

Your NRQL query must use one of the following summary, uniqueCount, or distribution functions to aggregate metrics:




Creates a summary metric data point for each time window (currently 1 minute). Use this if your NRQL query uses aggregator functions supported by the summary metric type, such as average, sum, min, or max.

Example rule-creation query:

SELECT summary(duration) AS 'service.responseTime' FROM Transaction
WHERE appName = 'Data Points Staging' FACET name, appName, host


Creates a uniqueCount metric data point for each 1-minute time window. Use this if your NRQL query uses the uniqueCount aggregator type.

Example rule-creation query:

FROM Transaction SELECT uniqueCount(request.headers.userAgent)
AS 'server.request.header.userAgent.uniqueCount'
WHERE appName = 'Browser Monitoring Router' FACET http.statusCode, name, appName, host


Creates a distribution metric data point for each 1-minute time window. Use this if your NRQL query uses aggregator functions such as percentile, histogram, min, max, average, sum, or count. Use only the attribute of interest as the argument, and discard the rest of the arguments from percentile or histogram. The generated metric supports any argument on percentile or histogram.

Example of creating a distribution rule:

SELECT distribution(duration) AS 'service.responseTime' FROM Transaction
WHERE appName = 'Data Points Staging' FACET name, appName, host

Simple count: summary(1) and sum

If you want a metric that's a simple count of the events, logs, or spans that match a particular WHERE clause, use the summary(1) metric. This metric type counts the number of specified events, logs, or spans per minute. When querying the created metric, use the sum method to see the result.

Example: If you want to create a metric named foo.count that counts the transactions named foo, the NRQL would look like this:

FROM Transaction SELECT summary(1) AS 'foo.count' WHERE name = 'foo'

Then, you would query it like this:

FROM Metric SELECT sum(foo.count) SINCE 30 minutes ago

For more information about metrics, see our documentation about metric types.

Rule-creation limits

These limits affect metric rules creation:



Account limits

An account can have a maximum of 1,000 metric-creation rules.

Metric rule limits

A rule can:

  • Create a maximum of 10 metrics.
  • Use only one type of data (events, logs, or spans).
  • Select a maximum of 20 attributes (facets) to include on a metric.

Time window limits

50K limit on unique metric-name/attribute-value combinations for a single metric in a 30 second time window. Normal cardinality limits on rollups will apply.

If the 50k in a 30 second window limit is exceeded, the rule is disabled and an NrIntegrationError event is created in that account that includes:

  • The rule details
  • A message about having too many facets
  • A newRelicFeature attribute value of eventToMetric

Cardinality limits

Rule-creation limits include limits on the number of unique combinations of metric name and attribute values. This limit exists because a large number of attributes and/or attribute values can lead to an exponential increase in the size of data reported.

Example metric creation rule that attaches five attributes:

FROM ProcessSample SELECT summary(ioTotalReadBytes)
WHERE entityType = 'ComputeSample'
FACET awsRegion, awsAvailabilityZone, commandName, entityName, processId

If each of the five attributes reported ten unique values within a one-minute time window, the number of unique metric-name/attribute combinations would theoretically have a maximum of 10x10x10x10x10, or 100,000. Multiple attributes with multiple unique values can lead to a large number of unique metric entries.

In practice, this isn't usually the case, because attributes are often related. For example, if one attribute is hostname and another is awsRegion, when you see hostname A, it will always be in AWS region B; you'd never see hostname A and other AWS region values.

This is why it's important, during the NRQL creation process, to use the uniqueCount function to verify how many unique metric-name/attribute-value combinations your NRQL query is generating.

Multiple metrics from one rule

A rule can create up to ten metrics. There are no functional differences between metrics created one at a time and those created with a single rule. Reasons for creating multiple metrics with a single rule:

Example creating multiple metrics with a single rule:

FROM Transaction SELECT uniqueCount(request.headers.userAgent) AS 'server.request.header.userAgent.uniqueCount',
summary(duration) AS 'server.duration', summary(totalTime) AS 'server.totalTime'
WHERE appName = 'Browser Monitoring Router' FACET http.statusCode, name, appName, host

Metric naming

A metric is given a name with the AS clause, as part of the NRQL rule-creation process. In the following NRQL example, the name of the metric is io.totalread.bytes:

FROM ProcessSample SELECT summary(ioTotalReadBytes) AS 'io.totalread.bytes' WHERE entityType = 'ComputeSample' FACET awsRegion, awsAvailabilityZone, commandName

If there is no name assigned with the AS clause, the metric name is the name of the queried attribute. In this example, if no name was assigned, the metric name would be ioTotalReadBytes.

Metric names

Requirements and recommendations


Requirements for naming a metric:

  • Less than or equal to 255 (UTF-16) 16-bit code units. One way to ensure you are under the limit is to keep each string under 127 of whatever is easiest to count.

  • No spaces.

  • Start with a letter.

    Examples of strong metric names:

  • rubyvm.memory.heap_used

  • redis.container.cpu.percent

  • memcached.process_virtual_memory.bytes

Length and structure

Decide on a name and structure that makes it easy for others to find, understand, and use this metric.

  • We recommend keeping your metric name under 40 characters for ideal readability. Longer names can get cut off or overlap with other names.
  • Your metric naming scheme will depend on your business logic. You may want to use namespaces to prefix your metric name, or your names may need to be more general.

Components within the name

If you want to create components within your metric name (like the source of metrics and the thing you’re measuring), we recommend going from broad to specific (left to right):

  1. Use a dot to separate those components in order to be consistent with our New Relic metric names.

  2. Then, use an underscore to separate words within the dots.




Avoid putting attributes in your metric name. Attributes are qualities of your metric that you can use to filter or facet your data, like cluster or availability zone.

Example: If you included availability zone in your metric name, it would mean, for that metric, you wouldn’t be able to see results across all availability zones.

Changing metric names

If you change a metric name, historical data will not be updated to that new name. To query or chart that historical data, you will need to specify the older metric name.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.