Skip to content

Latest commit

 

History

History
283 lines (220 loc) · 12 KB

query-metric-data-type.mdx

File metadata and controls

283 lines (220 loc) · 12 KB
Raw
title metaDescription redirects freshnessValidatedDate
Query the Metric data type
How to query New Relic's Metric data type, which is reported by our Metric API and the integrations that use it.
/docs/telemetry-data-platform/understand-data/metric-data/query-metric-data-type
/docs/data-ingest-apis/get-data-new-relic/metric-api/query-metric-data
/docs/data-ingest-apis/get-data-new-relic/metric-api/view-query-you-metric-data
/docs/data-ingest-apis/get-data-new-relic/metric-api/query-metric-data-type
/docs/telemetry-data-platform/get-data/apis/query-metric-data-type/
never

When metrics are reported to New Relic via the Metric API (including from integrations that use that API), the data is reported as the Metric data type and is available for querying.

This doc explains:

Query APM metric timeslice data [#metric-timeslice]

APM reports a specific type of data that we call metric timeslice data. For how to query that, see Query metric timeslice data.

You cannot query timeslice metrics in conjunction with dimensional metrics or event data. Any query involving `newrelic.timeslice.value` or an `apm.*` metric can only return APM metrics.

For information about other types of metrics, see Metric data types.

View and query your metrics [#view-and-query]

You can use NRQL to query your metric data in the query builder or using our NerdGraph API.

To query a metric, you can use the following query format:

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

For information about what functions are supported for what metric data types, see Metric data structure.

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

View example metric queries [#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 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
```

You can also do this using [wildcards](#query-multiple-metrics-wildcards), as explained below.

<Collapser id="example-math" title="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](#query-multiple-metrics-wildcards), as explained below.

<Collapser id="example-filters-timeseries" title="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.

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 = 'my-proxy') 
  AS 'Total (k8s)' 
  WHERE clusterName = 'my-cluster' AND podName LIKE 'my-pilot-%' 
  TIMESERIES
```

<Collapser id="example-view-raw-datapoints" title="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.

When querying these raw metric data points, there is a query time window limit of 48 hours. Any query attempting to access more than 48 hours of raw metric data will result in a query error.

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 [#query-multiple-metrics-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
  • FACET results 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:

  • myNeatProcess.algorithm1.duration
  • myNeatProcess.algorithm2.duration
  • myNeatProcess.algorithm3.duration

If used in a query, myNeatProcess.%.duration will return results for all three of the algorithms above. If you later create new algorithms named algorithm4, algorithm5, and algorithm6, the same query will return results for all six algorithms.

You can chart multiple metrics using a single query by using wildcards (`%`) in the `SELECT` clause. 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
```

<Collapser id="example-math" title="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
```

Return results for individual fields using getField() [#use-getField]

There are multiple types of Metric data (for example, gauge and count) and each type has several associated fields. For details on the types of fields available, see getField().

You can use getField() to extract those fields. For example, if you want to use a single value within a metric to do a comparison in a WHERE clause, you can use getField(metricName, field) or the shorthand syntax metricName[field].

The average value of a metric is computed as `total` over `count`, so the following query returns metric data where the result of the `average()` value function is greater than 2. 
```
FROM Metric 
SELECT average(apm.service.transaction.duration) 
WHERE appName = 'MyApp' 
AND getField(apm.service.transaction.duration, total) / getField(apm.service.transaction.duration, count) > 2
```

Or, you can use the shorthand:

```
FROM Metric 
SELECT average(apm.service.transaction.duration) 
WHERE appName = 'MyApp' 
AND apm.service.transaction.duration[total] / apm.service.transaction.duration[count] > 2
```
This example query returns a list of gauge metrics: 
```
FROM Metric 
SELECT uniques(metricName) 
WHERE getField(%, type) = 'gauge'
```

Or, you can use the shorthand:
```
FROM Metric 
SELECT uniques(metricName) 
WHERE %[type] = 'gauge'
```

Note the use of the `%` wildcard to target any matching `metricName`.

Explore metric data [#explore-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.

``` FROM Metric SELECT uniques(metricName) ```

<Collapser id="example-list-names-host" title="List all metric names for a particular host"

```
FROM Metric SELECT uniques(metricName) WHERE hostname = 'host1.mycompany.com'
```

<Collapser id="example-show-keys-metric" title="Show the attribute keys for a specific metric"

```
FROM Metric SELECT keyset() WHERE metricName = METRIC_NAME
```