Extract metric timeslice data

One type of New Relic data is metric timeslice data. There are several ways to query metric timeslice data:

• You can query APM metric timeslice data via NRQL (and therefore via our NerdGraph API).
• You can query any metric timeslice data via the REST API

This doc explains how to do this with the REST API. Note that the API is not intended for bulk data extraction of minute-by-minute data points.

Time based data

All time values returned by the REST API and the API Explorer are UTC (Universal Time Coordinated). Be sure to adjust the time values for data collection as necessary.

Time range considerations

The API uses the same mechanism for requesting data as the UI: it depends on the time range for the data you request. The objective is to optimize the number of data points returned and provide an easily digestible graph and report.

For example:

• If you request data from a time range of three hours or less, the API returns the one-minute data values originally collected.
• If you increase the time range to greater than three hours, the data values returned will be an average for two minutes.
• If you increase the time range to over six hours, the data values returned will be an average for five minutes, and so on.

Data aggregation schedule table

Here is a summary of the metric value retrieval for the time ranges available.

When the start time for a requested time range is older than eight days, data has been aggregated or averaged to one hour periods due to the data aggregation schedule. This means that for any one hour period, only a single data value is available. Obtaining data at less than an hourly period in the time range would cause oversampling, resulting in duplicate values being returned. Returning only ten values prevents oversampling and presents a smoother chart, which eliminates a possibly misleading "plateau" effect.

Controlling time period output

Sometimes the output data's granularity may be too fine, or the time period for the data returned may be too short. To control this, include the period= parameter in the query command as the number of seconds you want each time period to report. Ensure your specifications follow our data aggregation schedules.

Example #1: Following New Relic's table summarizing granularity of collected data, the following API call would normally return data in 30-minute periods, since the request is for 4 days (from=2018-02-13 and to=2018-02-17). By adding period=3600, the data will be returned as 60-minute periods.

curl -X GET "https://api.newrelic.com/v2/applications/$APP_ID/metrics/data.xml" \
     -H "Api-Key:$API_KEY" -i \
     -d'names[]=CPU/User+Time&from=2018-02-13T04:00:00+00:00&to=2018-02-17T04:00:00+00:00&period=3600'

You cannot specify a period smaller than the default for the time range you are requesting. For example:

• In the command example above, you can request 1-hour periods, since that is greater than the default (half hour) granularity for the time range.
• In the command example above, you cannot request 1-minute periods, since that is less than the default (half hour) granularity for the time range.

Example #2: If you request a range > 7 days but ≤ 3 weeks, where the default period is 3 hours, you can specify periods such as 6, 12, or 24 hours. However, you cannot request 1-hour periods, because that is less than the default (3 hours).

Data retention

How long data is available depends on the data retention for specific types of data.

Extracting non-existent metric timeslice data

Situations may arise where non-existent metric names are requested. For example:

• The metric timeslice data has not been created for one application, but exists for another. When the same metric extraction query is used on both of these applications, it will not be located for one.
• The metric name was incorrectly specified.

A successful response will include a 200 status code and metadata about the request. The metadata will contain the names of the metrics requested and the status of the request for those names.

Here is an example of output for a valid metric name, HttpDispatcher.

HTTP/1.1 200 OK
etag: "0dc87c63d8dff6b1a9714bdf7531ec09"
Content-Type: application/json
cache-control: max-age=0, private, must-revalidate
{
  "metric_data": {
    "from": "2016-01-28T18:06:06+00:00",
    "to": "2016-01-28T18:36:06+00:00",
    "metrics_not_found": [], <---<<< INDICATES NO INVALID METRIC NAMES REQUESTED
    "metrics_found": [
      "HttpDispatcher"       <---<<< INDICATES THIS METRIC NAME WAS VALID
    ],
    "metrics": [             <---<<< DATA RETURNED
      {
        "name": "HttpDispatcher",
        "timeslices": [
          {
            "from": "2016-01-28T18:03:00+00:00",
            "to": "2016-01-28T18:04:00+00:00",
            "values": {
              "average_response_time": 364,
              "calls_per_minute": 99800,
              "call_count": 99770,
              "min_response_time": 3.5,
              "max_response_time": 85000,
              "average_exclusive_time": 0,
              "average_value": 0.364,
              "total_call_time_per_minute": 36300,
              "requests_per_minute": 99800,
              "standard_deviation": 1900,
              "average_call_time": 364
            ...

Here is an example of output for a invalid metric name, Foo.

HTTP/1.1 200 OK
etag: "e51782cf7c5a5596139a7f5340c3de23"
Content-Type: application/json
cache-control: max-age=0, private, must-revalidate
{
  "metric_data": {
    "from": "2016-01-28T18:06:33+00:00",
    "to": "2016-01-28T18:36:33+00:00",
    "metrics_not_found": [
      "Foo"                   <---<<< INDICATES THIS METRIC NAME WAS INVALID
    ],
    "metrics_found": [],      <---<<< INDICATES NO VALID METRIC NAMES FOUND
    "metrics": []             <---<<< NO DATA RETURNED
  }
}