• EnglishEspañol日本語한국어Português
  • Log inStart now

Extract metric timeslice data

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

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

Important

The minimum time range for data requests is one minute (60 seconds). Requests for anything less will result in a 422 status code and no data will be returned. New Relic only collects data at one minute intervals.

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.

Tip

If the initial time for a requested time range is older than eight days, ten evenly spaced data points will be returned for any time range less than four days in length.

Data aggregation schedule table

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

Between this time range...

and this time range

Granularity of collected data

data age ≤ 8 days

data age > 8 days

≤ 3 hours

1 minute

10 evenly spaced
data points

> 3 hour

≤ 6 hours

2 minutes

> 6 hours

≤ 14 hours

5 minutes

> 14 hours

≤ 24 hours

10 minutes

> 1 day (24 hrs)

≤ 4 days (96 hrs)

30 minutes

> 4 days

≤ 7 days

1 hour

1 hour

> 7 days

≤ 3 weeks

3 hours

3 hours

> 3 weeks

≤ 6 weeks

6 hours

6 hours

> 6 weeks

≤ 9 weeks

12 hours

12 hours

> 63 days

3 days

3 days

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.

Important

Metric values that have existed in the past, but are no longer collected, will return a zero value.

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.

Response Metadata

Description

Response Metric Data

metrics_not_found

Lists all metric names for which matching data was not found in the requested time period.

Metric timeslice data will not be returned for these metrics

metrics_found

Lists all metric names for which matching data was found in the requested time period.

Metric timeslice data will be returned for these metrics

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
  }
}
Copyright © 2024 New Relic Inc.

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