View and query your metric data

Once you send metric data to New Relic via the Metric API, the dtaa is available for querying with NRQL. This document contains metric functions, examples, and sample queries.

View and query your metrics

Use NRQL to retrieve your metric data. To query a metric, use the following query in the chart builder or in Insights:

FROM Metric SELECT function(metric_name) WHERE attribute=value FACET attribute TIMESERIES

Below are the functions supported for each metric type:

Metric type Supported functions

Summary

count, sum, min, max, and average

Count

sum

Gauge

count, sum, min, max, average, and latest

Add the names of the metrics you want to chart with the appropriate value functions in the SELECT clause. The WHERE and FACET clauses can be used with attribute values. Remember to include the keyword TIMESERIES if you want to chart the data.

This example demonstrates how you could chart the CPU usage in seconds for cluster foo . This query breaks down CPU usage by container, given a count metric named container_cpu_usage_seconds_total with the attributes containerName and clusterName:

FROM Metric select sum(container_cpu_usage_seconds_total) 
  WHERE clusterName = 'foo' 
  FACET containerName 
  TIMESERIES

If you want the CPU usage per minute (the rate of change), then you can add the rate function to the query above.

FROM Metric select rate(sum(container_cpu_usage_seconds_total), 1 minute) 
  WHERE clusterName = 'foo' 
  FACET containerName 
  TIMESERIES

Example metric queries

The previous examples demonstrate basic forms of metric queries; but NRQL can also be used to chart, explore, and analyze your metric data.

Chart multiple metrics

Chart multiple metrics using a single query by providing a comma-separated list of metrics in the SELECT clause. For example, to chart the memory usage for a container along with the memory limit metric, use the following query:

FROM Metric 
  SELECT latest(container_memory_usage_bytes), latest(container_spec_memory_limit_bytes) 
  WHERE containerName = 'inventory' 
  TIMESERIES
Perform mathematical operations on metric data

Perform math operations on one or more metrics to compute a new, derived metric. To monitor available memory, you can calculate the percentage of available memory from the two metrics used in the previous example:

FROM Metric 
  SELECT (latest(container_spec_memory_limit_bytes) - latest(container_memory_usage_bytes)) 
    / latest(container_spec_memory_limit_bytes) 
    * 100 
    AS '% Memory Available' 
  WHERE containerName = 'inventory' 
  TIMESERIES
Use filters to select specific time series

In addition to using a WHERE clause which applies to everything in SELECT, NRQL provides another aggregation function called filter which can be used to select a specific time series to be charted or operated on. In the following example query, we chart a memory usage metric labeled "Total (k8s)" which is computed by adding together the memory usage of two specific containers within a pod:

FROM Metric 
  SELECT filter(
    latest(
      container_memory_usage_bytes), 
    WHERE containerName = 'discovery') 
  + filter(
    latest(
      container_memory_usage_bytes), 
    WHERE containerName = 'istio-proxy') 
  AS 'Total (k8s)' 
  WHERE clusterName = 'my-cluster' AND podName LIKE 'istio-pilot-%' 
  TIMESERIES
View the raw metric data points

When querying metric data using FROM Metric, New Relic automatically selects the specific aggregate to use in the query, depending on the length of the query window and any bucket size specified as an argument to the TIMESERIES keyword. This ensures efficient querying and chart resolution. If you want to override this behavior to view or operate on the raw metric data points, use the optional RAW keyword in your query.

This example shows how to list the last 20 data points received for a particular metric:

FROM Metric SELECT * WHERE metricName = 'container_fs_usage_bytes' LIMIT 20 RAW

Explore your metric data

The NRQL keyset and uniques functions can be used together with the metricName attribute (available on all metrics) to perform tasks like listing all the available metrics in your account or discovering the attributes available on a particular metric.

List all metric names in an account
FROM Metric SELECT uniques(metricName)
List all metric names for a particular host
FROM Metric SELECT uniques(metricName) WHERE hostname = 'host1.mycompany.com'
Show the attribute keys for a specific metric
FROM Metric SELECT keyset() WHERE metricName = METRIC_NAME

For more help

Recommendations for learning more:

  • Browse New Relic's Explorers Hub for community discussions about New Relic's APIs.
  • Use your preferred search engine to find other New Relic resources.