• English日本語한국어
  • Log inStart now

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:

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’

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:

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.