This document explains how to query the
Metric data type and contains example queries.
- View and query your metrics
- View example metric queries
- Query multiple metrics with wildcards
- Explore metric data
For information about other types of metric data, including metric timeslice data, see Metric data types.
View and query your metrics
Use NRQL to retrieve your metric data. To query a metric, use the following query format:
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|
count, sum, min, max, and average
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
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
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
View example metric queries
The previous examples demonstrate basic forms of metric queries, but NRQL can also be used to chart, explore, and analyze metric data.
- Chart multiple metrics
Chart multiple metrics using a single query by providing a comma-separated list of metrics in the
SELECTclause. 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
You can also do this using wildcards, as explained below.
- 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
You can also do this using wildcards, as explained below.
- Use filters to select specific time series
In addition to using a
WHEREclause which applies to everything in
SELECT, NRQL provides another aggregation function called
filterwhich can be used to select a specific time series to be charted or operated on.
The following example charts 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
TIMESERIESkeyword. 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
RAWkeyword 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
Query multiple metrics with wildcards
Wildcards are represented in NRQL by the
% character. If you want to query multiple metrics that use a standard naming convention, you can use the wildcard feature to return results for all of them without having to specify each metric name individually.
Wildcards can help you:
- Aggregate metrics together and chart the results
FACETresults by metric name in a chart
- Find and chart all metrics matching a given naming convention
Wildcards are particularly helpful if you later add new metrics matching an existing naming convention. By using
% instead of writing out each metric name in your query, you won't have to rewrite the query when you add new metrics.
Let's say you have multiple algorithms that perform a similar task. You can define the following metrics, which show the duration of the different algorithms:
If used in a query,
myNeatProcess.%.duration will return results for all three of the algorithms above. If you later create new algorithms named
algorithm6, the same query will return results for all six algorithms.
- Chart multiple metrics with wildcards
You can chart multiple metrics using a single query by using wildcards (
%) in the
SELECTclause. For example, to query all the algorithms in the example above and plot a line on the chart for each algorithm's average duration, use the following query:
FROM Metric SELECT average(myNeatProcess.%.duration) FACET metricName TIMESERIES
- Perform mathematical operations on metric data with wildcards
You can also use wildcards to perform math operations on multiple metrics and compute a new metric. You can calculate the mean duration for all algorithms listed in the example above:
FROM Metric SELECT average(myNeatProcess.%.duration) TIMESERIES
You can calculate what percentage of overall runtime a single algorithm takes:
FROM Metric SELECT myNeatProcess.algorithm1.duration / sum(myNeatProcess.%.duration) TIMESERIES
Explore metric data
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
Query metric timeslice data
Metric timeslice data is a specific type of metric data reported by New Relic APM, Browser, and Mobile. See Query metric timeslice data.