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 alert on this type of data. To explore your timeslice data, see Explore your metrics.

Why query metric timeslice data?

New Relic reports 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, , and browser (for more details, see metric timeslice data).

metrics are automatically converted 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.

Important

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 our query builder. This experience offers full NRQL functionality, and also gives helpful auto-complete suggestions and feedback on query errors.

You can also:

Make NRQL queries using our NerdGraph (GraphQL) API
Alert on NRQL queries using NRQL alert conditions

How to construct a query

In APM, some charts have the option to view the NRQL query that generated that chart. This is a good starting point for understanding how to query metrics. The NRQL query below is slightly modified from the error rate chart on the 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 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 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’`

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

Learn how to see all metrics available to you. To get the metric unit for a given metric name, you can use a query like:

FROM Metric
  SELECT unit
  WHERE appName = 'YOUR_APP_NAME'
  AND metricName = 'METRIC_NAME'

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 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 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.

Overview metrics

Overview metrics allow you to get a breakdown of where time is spent during execution. These metrics are unique in a few ways:

They are a combination of many timeslices.
They are designed to work with the average aggregator function only.
Code executed concurrently will show the combined execution time.

For example, if your service calls a MySQL database in 3 concurrent threads with an average response time of 0.1 seconds for each thread, the MySQL segment will show up as 0.3.

Several overview metrics are provided for different purposes:

Metric name	Description	Attributes
`apm.service.overview.web`	Breakdown of time spent in different parts of the service for web transactions	`segmentName`
`apm.service.overview.other`	Breakdown of time spent in different parts of the service for background/non-web transactions	`segmentName`
`apm.service.transaction.overview`	Breakdown of time spent in a specific transaction	`metricTimesliceName`
`apm.key.transaction.overview`	Breakdown of time spent in a specific key transaction	`segmentName`

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.

Important

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 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.

Recommended aggregator functions

Recommended NRQL aggregator functions include:

apdex
average
sum
count
rate
uniques

Query examples

Some examples of querying metric timeslice data:

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

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

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.

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

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 APM transactions page 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

Query APM metric timeslice data with NRQL

Why query metric timeslice data?

Important

Where to query?

How to construct a query

How metric timeslice data is converted

Attributes

Overview metrics

Generic queries with the `newrelic.timeslice.value` metric

Important

When to use `newrelic.timeslice.value`?

Get available metrics

Facet on a wildcarded metric name segment

Recommended aggregator functions

Query examples

Facet by multiple app names

Throughput-per-minute rate

Facet by host-related attributes

Query of average duration of a metric

Break down average time spent in a transaction by its component segments

Query APM metric timeslice data with NRQL

Why query metric timeslice data? .css-21sua1{background:none;border:none;width:0;padding:0;}

Important

Where to query?

How to construct a query

How metric timeslice data is converted

Attributes

Overview metrics

Generic queries with the newrelic.timeslice.value metric

Important

When to use newrelic.timeslice.value?

Get available metrics

Facet on a wildcarded metric name segment

Recommended aggregator functions

Query examples

Throughput-per-minute rate

Facet by host-related attributes

Query of average duration of a metric

Break down average time spent in a transaction by its component segments

Why query metric timeslice data?

Generic queries with the `newrelic.timeslice.value` metric

When to use `newrelic.timeslice.value`?