--- title: Query APM metric timeslice data with NRQL source: https://docs.newrelic.com/docs/data-apis/understand-data/metric-data/query-apm-metric-timeslice-data-nrql --- APM reports metric data in the form of [metric timeslice data](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#timeslice-data), and you can use [NRQL](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/introduction-nrql-new-relics-query-language) to query and alert on this type of data. To explore your timeslice data, see [Explore your metrics](https://docs.newrelic.com/docs/query-your-data/explore-query-data/data-explorer/introduction-data-explorer#blocks-metrics). ## Why query metric timeslice data? [#why] New Relic reports [metrics in several ways](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#metrics). 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 monitoring, and browser (for more details, see [metric timeslice data](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#timeslice-data)). APM 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](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-nrql-tutorial). 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](https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-data/collect-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? [#where] We recommend querying APM metric timeslice data using our [query builder](https://docs.newrelic.com/docs/chart-builder/use-chart-builder/choose-data/use-advanced-nrql-mode-specify-data). 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](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph) - Alert on NRQL queries using [NRQL alert conditions](https://docs.newrelic.com/docs/alerts-applied-intelligence/new-relic-alerts/alert-conditions/create-nrql-alert-conditions) ## How to construct a query [#form-query] In APM, some charts have the option to [view the NRQL query that generated that chart](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/introduction-nrql-new-relics-query-language). 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 APM summary page. ```sql 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](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#dimensional-metrics), and metric timeslice data is stored as this data type. For general tips on querying `Metric` data, see [Metric query examples](https://docs.newrelic.com/docs/data-ingest-apis/get-data-new-relic/metric-api/view-query-you-metric-data). | | `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](#timeslice-conversion). Note that you can use other [aggregator functions](#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](#multiple-app-names). 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](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/introduction-nrql). For more queries, see [Query examples](#query-examples). ## How metric timeslice data is converted [#timeslice-conversion] The conversion of original APM 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](#generic-queries). Here are how the original [APM timeslice metrics](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#timeslice-data) 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](#get-list). To get the metric unit for a given metric name, you can use a query like: ```sql 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](https://docs.newrelic.com/docs/using-new-relic/data/understand-data/new-relic-data-types#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. | ## Overview metrics [#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 [#generic-queries] 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](#timeslice-conversion) when possible. ### When to use `newrelic.timeslice.value`? [#when-to-use] Given a metric timeslice name, you can query to see if it has a converted dimensional metric equivalent with this syntax: ```sql 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 [#get-list] To get a list of available metrics for an application, you can use a query like: ```sql SELECT uniques(metricTimesliceName) FROM Metric WHERE appName = 'YOUR_APP_NAME' AND newrelic.timeslice.value IS NOT NULL ``` ## Facet on a wildcarded metric name segment [#wildcard] 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](#generic-queries) of a custom metric that facets on a wildcarded metric segment: ```sql 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 [#aggregator-functions] Recommended NRQL [aggregator functions](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/nrql-syntax-clauses-functions#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`](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/nrql-syntax-clauses-functions#sel-where) to specify two applications and then facet by them: ````sql 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`](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/nrql-syntax-clauses-functions#func-rate) function: ````sql 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: ````sql 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](/node/36916/revisions/402556/view#infrastructure-attributes), like `host.bootId`. ```` **Query of average duration of a metric** This queries the average duration for a metric using [`average`](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/nrql-syntax-clauses-functions#func-average): ````sql 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 APM transactions page for a service entity: ````sql 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 ``` ````