Events-to-metrics: Create metrics

In New Relic, the events-to-metrics service lets you define rules for creating metrics from your event-type data. This document contains:

Create an events-to-metrics rule

Here's an overview of creating an events-to-metrics rule:

  1. First, construct an events-to-metrics rule using NRQL.

  2. Next, construct a NerdGraph (GraphQL format) API request that contains the NRQL rule you've created in Step 1.
  3. Finally, create the metric by making the API request.

Once a metric is created, you can query and chart that metric using NRQL.

Step 1. Create NRQL query rule

The most important part of creating an events-to-metrics rule is constructing the NRQL query that defines the metric. You can create up to 10 metrics with a single NRQL query by following this procedure:

  1. Using a NRQL interface, construct a query for the metric you want to create. For example:
    FROM ProcessSample SELECT average(ioTotalReadBytes)
    WHERE nr.entityType = 'HOST'
    
  2. Edit the query to use one of the three available metric types:

    • summary: Use if the query's function is min, max, sum, count, or average.
    • uniqueCount: Use if the query's function is uniqueCount.
    • distribution: Use if the query's function is percentile or histogram.

    This example query uses average, so you'd use summary:

  3. FROM ProcessSample SELECT summary(ioTotalReadBytes) 
    WHERE nr.entityType = 'HOST'
    
  4. Decide on the attributes you want to attach to the metric, following the limits on the cardinality of unique metric-name/attribute-value combinations.

    Recommendation: Run a separate query to ensure this count isn't over 50,000 for a 24-hour window. For example:

    FROM ProcessSample
    SELECT uniqueCount(awsRegion, awsAvailabilityZone, commandName)
    WHERE nr.entityType = 'HOST'
    SINCE 1 DAY AGO
  5. To be able to aggregate and filter your metrics, add the attributes you want to attach to the metric using the FACET clause. For example:

    FROM ProcessSample
    SELECT summary(ioTotalReadBytes) WHERE nr.entityType = 'HOST' 
    FACET awsRegion, awsAvailabilityZone, commandName
  6. Set the name of the metric using the AS function. For example:

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

Once your NRQL rule is complete, you'll use it when you create the API request.

Step 2. Create API request

Once you've built the events-to-metrics NRQL rule, you'll build the API request. You can use our NerdGraph API tool to explore the data structure and to construct and make your request.

In the following example NerdGraph API request, we've used the same NRQL rule from step 1. The IO Total Read Bytes Rule creates a metric named io.totalread.bytes. (The rule name can have spaces, which differs from the metric naming rules.)

mutation {
  eventsToMetricsCreateRule(rules: {
    name: "io.totalread.bytes for computeSample entities",
    description:"Created by Zach on March 27, 2019. Used by team Network.",
    nrql:"FROM ProcessSample SELECT summary(ioTotalReadBytes) AS 'io.totalread.bytes' WHERE nr.entityType = 'ComputeSample' FACET awsRegion, awsAvailabilityZone, commandName",
    accountId: 123456
  })
  {
    successes {
      id
      name
      nrql
      enabled
    }
    failures {
      submitted {
        name
        nrql
        accountId        
      }
      errors {
        reason
        description
      }
    }
  }
}
Request elements Comments
mutation

One of the basic API operation types.

eventsToMetricsCreateRule

The method being called to create a rule.

rules

Takes four parameters:

  • name: The name of the rule.
  • description: Optional. The description of the rule. We recommend you include information about who created the metric data and who will be using the data.
  • accountId: The New Relic account ID where the events live and the metrics will be created.
  • nrql: The NRQL query that creates the rule. For more on this, see Create NRQL query.
successes and submitted blocks

Here you define the data returned by a successful or failed response. Available parameters for these blocks include:

  • id (ruleId for submitted)
  • name
  • description
  • nrql
  • enabled (enabled/disabled status)
  • accountId
ruleId and accountId

If a failure occurs, then the submitted ruleId and accountId will be returned along with the error reason and error description.

Example response

Here's an example of a returned response:

{
  "data": {
    "eventsToMetricsCreateRule": {
      "failures": [],
      "successes": [
        {
          "enabled": true,
          "id": "46",
          "name": "io.totalread.bytes for computeSample entities",
          "nrql": "FROM ProcessSample SELECT summary(ioTotalReadBytes) AS 'io.totalread.bytes' WHERE nr.entityType = 'ComputeSample' FACET awsRegion, awsAvailabilityZone, commandName"
        }
      ]
    }
  }
}

To check that the rule was created correctly, you can run a query to return that rule using its ID.

For tips on querying the metrics you've created, see Query and chart your metrics.

Step 3. Create an event-to-metrics rule with API request

When your API request is ready, you can use the NerdGraph API to make the request, which will create the metrics. For instructions on using this, see Use NerdGraph.

Query and chart your metrics

Once you've created an events-to-metrics rule, the new metric data should appear in New Relic in a few minutes. To view your data:

  1. Go to a NRQL query interface and run the following query. This will give you the name of all your metrics.
    SELECT uniques(metricName) FROM Metric
    
  2. Pick the metric of interest and run the following to see the available attributes:
    SELECT * FROM Metric where metricName = 'yourMetric'

The available NRQL aggregator functions available will depend on the metric type you've created. For example, if you've created a summary metric type, you will be able to use the count, sum, max, min, and average aggregator functions, as shown in the following query:

SELECT count(appStartResponseTime), sum(appStartResponseTime), max(appStartResponseTime), min(appStartResponseTime),  average(appStartResponseTime) FROM Metric 

If you created a uniqueCount metric type, you can only use the uniqueCount function, as shown in the following query:

SELECT uniqueCount(playbackErrorStreamUniqueCount) * 100 / uniqueCount(streamUniqueCount) AS '% of Streams Impacted' FROM Metric

If you created a distribution metric type, use the percentile or histogram functions, as shown in the following queries:

SELECT percentile(service.responseTime, 95) FROM Metric
SELECT histogram(service.responseTime, 10, 20) FROM Metric

If you don't see expected data, follow the troubleshooting procedures.

Troubleshooting

If you receive a message like Cannot parse the unexpected character "\u201C”, verify the quotes in the NerdGraph call are not smart quotes (curly quotes). Our NerdGraph API only accepts straight quotes.

Rule-creation requirements and recommendations

Here are some limits, requirements, and recommendations for events-to-metrics rule creation:

Available metric types: summary, uniqueCount, and distribution

A NRQL query must use one of the following functions to aggregate metrics:

  • summary: Creates a summary metric data point for each time window (currently 1 minute). Use this if the NRQL query you are creating a metric for uses aggregator functions supported by the summary metric type, such as average, sum, min, or max. An example rule-creation query using summary:
  • SELECT summary(duration) AS 'service.responseTime' FROM Transaction 
    WHERE appName = 'Data Points Staging' FACET name, appName, host
    
  • uniqueCount: Creates a uniqueCount metric data point for each time window (currently 1 minute). Use this if the NRQL query you're creating a metric for 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 httpResponseCode, name, appName, host  
    
  • distribution: Creates a distribution metric data point for each time window (currently 1 minute). Use this if the NRQL query you are creating a metric for uses aggregator functions such as percentile, histogram, min, max, average, sum, or count. Use only the attribute of interest as argument, and discard the rest of 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

If you want a metric that's a simple count of the events matching a particular WHERE clause, you can do this by using summary(1) metric. This metric type counts the number of specified events per minute. When querying the created metric, you can use the sum method to see the result. For example, if you wanted to create a metric named foo.count that counts the transactions named foo, the NRQL would look like:

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

and you would query it like:

FROM Metric SELECT sum(foo.count) SINCE 30 minutes ago
For more information on metrics, see our docs.
Rule-creation limits

Some limits affecting metrics creation:

  • An account can have a maximum of 1000 metric-creation rules.
  • A rule can create a maximum of 10 metrics.
  • A rule can use only one event type.
  • A rule can select a maximum of 20 attributes (facets) to include on a metric
  • 50K limit on unique metric-name/attribute-value combinations for a single metric in a 24-hour time window. If this 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, and a newRelicFeature of eventToMetric.
  • There is also a limit on total unique metric-name/attribute-value combinations in a 24-hour time window for an account, which is equal to three times the purchased monthly average data points per minute, up to a maximum of 10M.
Cardinality limits for unique metric-name/attribute-value combinations

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. Let's look at an 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.

Create multiple metrics with one rule

An events-to-metrics rule can create up to 10 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:

Here's an example of 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 httpResponseCode, name, appName, host
Metric naming: rules and recommendations

A metric is given a name with the AS clause, as part of the NRQL rule-creation process. For example, 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.

Examples of strong metric names:

  • rubyvm.memory.heap_used
  • redis.container.cpu.percent
  • memcached.process_virtual_memory.bytes

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.

Recommendations for naming:

  • We recommend keeping your keeping your metric name under 40 characters for ideal readability. Longer names can get cut off or overlap with other names.
  • Decide on a name and structure that makes it easy for others to find, understand, and use this metric. Your metric naming scheme will depend on your business logic. You may have namespaces that you want to prefix your metric name with or your names may need to be more general.
  • If you do 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), using a dot to separate those components in order to be consistent with our New Relic metric names, and using an underscore to separate words within the dots (for example, application.page_view.duration).
  • Avoid putting attributes in your metric name. Attributes are qualities of your metric that you might use to filter or facet your data, like cluster or availability zone. 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.
  • If you change a metric name, historical data will not be updated to that new name and you will need to specify the older metric name in order to query or chart that historical data.

For more help

If you need more help, check out these support and learning resources: