Query APM metric timeslice data with NRQL

APM reports metric data in the form of metric timeslice data, and you can use NRQL to query and facet this type of data. To explore timeslice data in the data explorer, see Explore your metrics.

Why query metric timeslice data?

We report metrics in several ways. One variety of metric data we call metric timeslice data; this is the type of data used to generate many of the charts in APM, Mobile, and Browser (for more details, see metric timeslice data).

Historically, this type of data couldn't be queried via our query language, NRQL. But now we are converting popular APM metrics from metric timeslice data to more-detailed dimensional metric data, which opens them up for querying via NRQL and via our NerdGraph API. This capability allows you to create powerful, in-depth custom visualizations of these important APM metrics. And this includes being able to query your custom metrics.

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.

Where to query?

We recommend querying APM metric timeslice data using New Relic One query builder in advanced mode. This experience offers full NRQL functionality, and also gives helpful auto-complete suggestions and feedback on query errors.

You can also incorporate NRQL queries in our NerdGraph (GraphQL) API.

How to construct a query

In APM, some charts have the option to view the NRQL query that generated that chart. This can be a good option for understanding how to query metrics. The NRQL query examined below is slightly modified from the error rate chart on the APM summary page.

FROM Metric
  SELECT count(apm.service.error.count) / count(apm.service.transaction.duration)
  WHERE (entity.guid = 'AN_ENTITY_GUID')
  AND (transactionType = 'Web')
  SINCE 1 day ago TIMESERIES

Here is a breakdown of how the parts of this query work:

Query segment What does it do?
FROM Metric

Metric is one of our core data types, and metric timeslice data is stored as this data type. For general tips on querying Metric data, see Metric query examples.

SELECT count(apm.service.error.count) / count(apm.service.transaction.duration)

This math generates a count of errors out of a total count of transaction metrics. This query uses the converted metric names.

Note that you can use other aggregator functions.

WHERE (entity.guid = 'AN_ENTITY_GUID')

You must specify at least one data source. You can select a single entity's GUID, as shown here, or you can select multiple sources. This query uses entity.guid, but you can also use appId or appName.

AND (transactionType = 'Web')

Sets the transaction type to web, meaning that background/non-web transactions won't be counted.

SINCE 1 day ago

Selecting a time range.

TIMESERIES

This optional clause displays the results in a time-based chart.

For general information on NRQL syntax, including FROM, FACET, and TIMESERIES, see Intro to NRQL.

For more queries, see Query examples.

How metric timeslice data is converted

The conversion of original APM metric timeslice metrics into dimensional metrics that are available for querying is an ongoing process and isn't complete. If you don't see a metric you're looking for in this section, see Generic queries.

Here are how the original APM metric timeslice metrics are converted into dimensional metrics:

Metric timeslice structure Dimensional metric structure

APM metric names are represented as single strings of segments separated by forward slashes.

For example, the “Datastore/statement/MySQL/users/select” metric represents the time spent in a select database operation on the users table.

A single dimensional metric named apm.service.datastore.operation.duration represents the entire group of datastore metrics.

This metric has three attributes representing the data values encoded into the metric name, datastoreType, table and operation:

datastoreType = ‘MySQL’

table = ‘users’

operation = ‘select’

Some of the APM metrics made available as dimensional metrics:

Metric name Description Attributes
apm.service.cpu.usertime.utilization Time spent in user-mode code percentage
apm.service.datastore.operation.duration Response time for database calls broken out by table operations datastoreType, table, operation
apm.service.error.count Summary error count metrics transactionType
apm.service.external.host.duration Response time for external calls broken out by external host name external.host
apm.service.instance.count Count of the number of agent instances
apm.service.memory.physical Process memory in MB
apm.service.transaction.apdex Apdex scores per transaction transactionName, transactionType
apm.service.transaction.duration Response time per transaction keyTransactionName, transactionName, transactionType
apm.service.transaction.error.count Error counts per transaction keyTransactionName, transactionName, transactionType
apm.service.transaction.external.duration External call response time by transaction type transactionType

Learn how to see all metrics available to you.

To understand more about the general structure of metric timeslice data, including some common examples, see Metric timeslice data.

Attributes

These attributes are available in addition to the metric-specific attributes listed in the APM metrics table above.

Name Description
appName The name of the application.
appId The ID of the application.
entity.guid The GUID of the application.
host The host of the monitored process.
host.bootId The ID of the boot of the host, if available.
host.displayName The display_name of the host, if it was set in the agent.
instanceName For Java APM agents, host : port
metricName The name of the dimensional metric.
metricTimesliceName The timeslice name of the legacy metric.
scope (Optional) The timeslice name of the legacy metric that this metric is "scoped" to. Metrics with a scope belong to it--their measurements apply to the context of the metric named in the scope attribute. See below for examples.

Generic queries with the newrelic.timeslice.value metric

For metrics that haven't been converted to dimensional metrics, or for your own custom metrics, we have a dimensional metric named newrelic.timeslice.value.

We recommend using the dimensional metrics from the table above when possible.

When to use newrelic.timeslice.value?

Given a metric timeslice name, you can query to see if it has a converted dimensional metric equivalent with this syntax:

FROM Metric
SELECT uniques(metricName)
WHERE metricTimesliceName = 'Datastore/statement/MySQL/test/select'

If the only metric name returned is newrelic.timeslice.value, you'll need to query your data using this general approach.

Get available metrics

To get a list of available metrics for an application, you can use a query like:

SELECT uniques(metricTimesliceName) 
FROM Metric WHERE appName='YOUR_APP_NAME' 
AND newrelic.timeslice.value IS NOT NULL

Facet on a wildcarded metric name segment

Some metric timeslice names include attribute values as segments of the metric name. For example, our APM agents report metrics by tracking the duration of external calls using this format:

External/{externalHost}/all

Here, {externalHost} represents the host name for the outbound network call.

Here's an example of a generic newrelic.timeslice.value query of a custom metric that facets on a wildcarded metric segment:

FROM Metric SELECT count(newrelic.timeslice.value) 
  WHERE appName = 'MY APP' 
  WITH METRIC_FORMAT 'Custom/Labels/{action}' 
  TIMESERIES FACET action

In this query, {action} creates a temporary attribute, action, which is then used by FACET action. You can use any name you want, because it's only an attribute that exists for the duration of the query. You should choose a name that does not conflict with an existing attribute name.

Here's another example of a faceted wildcard query:

New Relic One chart builder - metric timeslice NRQL query
This shows a NRQL query of metric timeslice data that facets the rate of Flask functions by the wildcarded process name.

Recommended aggregator functions

Recommended NRQL aggregator functions include:

  • apdex
  • average
  • sum
  • count
  • rate
  • uniques

Query examples

Some examples of querying metric timeslice data:

Facet by multiple app names

This query uses WHERE… IN to specify two applications and then facet by them:

FROM Metric
  SELECT rate(count(apm.service.transaction.duration), 1 minute) as 'Web throughput' 
  WHERE appName IN ('MY_APPLICATION', 'MY_OTHER_APPLICATION')
  AND (transactionType = 'Web')
  FACET appName
  TIMESERIES
Throughput-per-minute rate

This query displays requests-per-minute chart using the rate function:

FROM Metric 
  SELECT rate(count(apm.service.transaction.duration), 1 minute) as 'HttpDispatcher requests_per_minute' 
  WHERE appName = 'MY_APPLICATION' 
  AND (transactionType = 'Web')
  TIMESERIES SINCE 3 days ago
Facet by host-related attributes

This query displays a requests-per-minute chart faceted by host name:

FROM Metric 
  SELECT count(apm.service.transaction.duration) as 'HttpDispatcher requests_per_minute' 
  WHERE appName = 'MY_APPLICATION' 
  AND (transactionType = 'Web')
  TIMESERIES SINCE 3 hours ago 
  FACET host 
  LIMIT 20

Instead of using host, you can facet by other host-related attributes, like host.bootId.

Query of average duration of a metric

This queries the average duration for a metric using average:

FROM Metric 
  SELECT average(apm.service.transaction.duration) as 'HttpDispatcher average duration' 
  WHERE appName = 'MY_APPLICATION' 
  AND (transactionType = 'Web') 
  TIMESERIES SINCE 3 days ago
Break down average time spent in a transaction by its component segments

This query breaks down the average duration of single transaction (in this case, the show action in the UsersController of a Rails app named MY_APPLICATION) by the top 20 individual segments (database queries, external service calls, garbage collection time, etc.). It reproduces much of the "Application breakdown" chart as seen on the Transactions page In New Relic One for a service entity:

FROM Metric 
  SELECT average(newrelic.timeslice.value, exclusiveTime: true) as 'duration, seconds' 
  WHERE appName = 'MY_APPLICATION' 
  AND scope = 'Controller/users/show'
  LIMIT 20 
  FACET metricTimesliceName
  TIMESERIES SINCE 3 days ago

For more help

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