Report metrics via the Metric API

Use the Metric API to send custom metrics to the New Relic platform. This document includes a quick start to send your first custom metric, plus detailed information on how to format and send your metric data.

Quick start: Send metric data

Metric data is submitted to New Relic through an HTTP POST request. Each request is composed of one or more metric data points, which consist of a metric name, a timestamp, and a value.

Follow this example to send your first metric data points to New Relic:

  1. Find or register an Insert API key for your account (go to insights.newrelic.com > Manage data > API keys).

  2. Insert your API key into the following JSON and then send the JSON to our endpoint. This example creates a single metric data point for a metric named memory.heap, but you can create additional attributes or data points by specifying metric types or adding optional common blocks.

    curl -vvv -k -H "Content-Type: application/json" \
    -H "Api-Key: YOUR_API_KEY_HERE" \
    -X POST https://metric-api.newrelic.com/metric/v1 \
    --data '[{ \
            "metrics":[{ \
               "name":"memory.heap", \
               "type":"gauge", \
               "value":2.3, \
               "timestamp":CURRENT_TIME_IN_MILLISECONDS_HERE, \
               "attributes":{"host.name":"dev.server.com"} \
               }] \
        }]'
    
  3. The metric should be available in New Relic in a few seconds. You should be able to see it using this NRQL query in the chart builder or in Insights:

    FROM Metric SELECT max(memory.heap) TIMESERIES
    

Endpoint URL

Use an HTTP POST when sending metric data to the metric API endpoint:

https://metric-api.newrelic.com/metric/v1

If your account hosts data in the EU data center, ensure you're using the proper API endpoints for EU region accounts.

HTTP request headers

Include the following HTTP request headers with the POST request. You can send some parameters as query parameters instead of request headers.

Header Send as a query parameter? Details
Content-Type No Required. Must be application/json.
Content-Length No Required (usually set automatically by the HTTP client). The length of the request body in octets (8-bit bytes) unless sent with chunked encoding. This header is generally set by default by the underlying HTTP client sending the data and in most cases should not require any additional effort by the end user.
Api-Key Yes Required. The Insert API key authenticates you to use the Metric API. If this is provided as both a header and a query parameter, the values must match.
Content-Encoding No Required if GZIP. The value must be GZIP or Identity. If no value is present, then Identity is assumed.

HTTP request body

The body of the HTTP POST request must be in JSON format. The following describes the requirements and recommendations for the JSON payload.

The JSON payload uses this structure:

  • The JSON payload is an array of maps.
  • Each map must contain a metrics key whose value is an array containing one or more metric data points.
  • A metric data point is identified by a name, type, and value along with an optional set of attributes.
JSON payload creating two metrics

This example payload creates two metrics. service.errors.all is a count metric with three attributes and service.memory is a gauge metric with two attributes.

[
  {
    "metrics": [
      {
        "name": "service.errors.all",
        "type": "count",
        "value": 15,
        "timestamp": CURRENT_TIME_IN_MILLISECONDS_HERE,
        "interval.ms": 10000,
        "attributes": {
          "service.response.statuscode": "400",
          "host.name": "dev.server.com",
          "service.name": "foo"
        }
      },
      {
        "name": "service.memory",
        "type": "gauge",
        "value": 2.7,
        "timestamp": CURRENT_TIME_IN_MILLISECONDS_HERE,
        "attributes": {
          "host.name": "dev.server.com",
          "app.name": "foo"
        }
      }
    ]
  }
]   

Each metric data point map in the metrics array uses the following key-value structure:

Key Description
name
string
Required. The name of the metric. The value must be less than 255 characters.
value
string
Required. The value varies depending on the metric type. For gauge and count the value should be a single number. For summary, the value should be a map with key-value pairs specifying the count, sum, min, and max.
timestamp
long
Required. The metric's start time in Unix time. Defaults to the current time in UTC timezone. This field also support seconds, microseconds, and nanoseconds. However, the data will be converted to milliseconds for storage and query.
interval.ms
positive long

Required for count and summary metric types. The length of the time window.

type Recommended. This should be one of the supported metric types. If you do not specify a type, then this will default to a gauge.
attributes
strings, JSON numbers, or booleans
Recommended. A map of key value pairs associated with this specific metric. Values can be strings, JSON numbers, or booleans. Keys are case-sensitive and must be less than 255 characters.

The metric type determines how the data is aggregated over longer time windows. It also determines which query functions you can use to visualize the data. The Metric API supports these types:

metric types description available query functions
gauge

Represents a value that can increase or decrease with time. Examples of gauges include the temperature, CPU usage, and memory.

For example, there is always a temperature, but you are periodically taking the temperature and reporting it.

The value must fit into the range of a Java double.

  • latest
  • min
  • max
  • average
  • sum
  • count
count

Measures the number of occurrences of an event. The count should be reset to 0 every time the metric is reported. Examples include cache hits per reporting interval and the number of threads created per reporting interval.

You must specify a value for interval.ms when using the count metric type.

The value must be a positive double.

  • sum

Generally, you want to take the rate of the sum: From Metric select rate(sum(myMetric), 1 minute) . . .

summary

Used to report pre-aggregated data, or information on aggregated discrete events. A summary includes a count, sum value, min value, and max value. The count value must be positive. Examples include transaction count/durations and queue count/ durations.

You must specify a value for interval.ms when using the summary metric type.

  • average
  • min
  • max
  • count
  • sum
JSON payload with three metric types

Here's an example payload containing one metric data point for each metric type:

[
  {
    "metrics": [
      {
        "name": "cache.misses",
        "type": "count",
        "value": 15,
        "timestamp": CURRENT_TIME_IN_MILLISECONDS_HERE,
        "interval.ms": 10000,
        "attributes": {
          "cache.name": "myCache",
          "host.name": "dev.server.com"
        }
      },
      { 
        "name": "temperature", 
        "type": "gauge", 
        "value": 15, 
        "timestamp": CURRENT_TIME_IN_MILLISECONDS_HERE, 
        "attributes": { 
          "city": "Portland", 
          "state": "Oregon" 
        } 
      },
      {
        "name": "service.response.duration",
        "type": "summary",
        "value": {
          "count": 5, 
          "sum": 0.004382655, 
          "min": 0.0005093, 
          "max": 0.001708826
        },
        "interval.ms": 10000, 
        "timestamp": CURRENT_TIME_IN_MILLISECONDS_HERE,
        "attributes": {
          "host.name": "dev.server.com",
          "app.name": "foo"
        }
      }
    ]
  }
]   

If you want to include a set of attributes on multiple metrics (and not add the same attributes for each metric), you can use the common block. This is an optional map which specifies information that applies to all associated metric data points. Values in the common section will be overridden if the same key exists on a metric data point. The block can include:

attribute description
timestamp
long
The metric's start time in Unix time. This defaults to the current time in the UTC timezone. This field also supports seconds, microseconds, and nanoseconds. However, the data will be converted to milliseconds for storage and later querying.
interval.ms
positive long

Required for count and summary.The length of the time window.

attributes
strings, JSON numbers, or booleans
A map of key-value pairs associated with this specific metric. Values can be strings, JSON numbers, or booleans.
Example of common attributes

In the following example payload, three metrics are sent. All three metrics share app.name and host.name attributes, specified in the common block. Each metric also has a unique value for another attribute, server.response.statuscode.

[
  {
    "common" : {
      "timestamp": 1531414060739,
      "interval.ms": 10000,
      "attributes": {
        "app.name": "foo",
        "host.name": "dev.server.com"
      }
    },
    "metrics": [
      {
        "name": "service.errors.all",
        "type": "count",
        "value": 9,
        "attributes": {
          "service.response.statuscode": "400"
        }
      },
      {
        "name": "service.errors.all",
        "type": "count",
        "value": 4,
        "attributes": {
          "service.response.statuscode": "500"
        }
      },
      {
        "name": "service.response.duration",
        "type": "summary",
        "value": {
          "count": 5,
          "sum": 0.004382655,
          "min": 0.0005093,
          "max": 0.001708826
        },
        "attributes": {
          "service.response.statuscode": "200"
        }
      }
    ]
  }
]

Response validation and status codes

The Metric API returns a 202 response code for successful requests. When your data is accepted, an HTTP 202 response code is returned with a response structure like this:

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=UTF-8
Content-Length: 52
Access-Control-Allow-Methods: GET, POST, PUT, HEAD, OPTIONS
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Connection: keep-alive

{"requestId":"f0e7bfff-001a-b000-0000-01682bcf4565"}

A 202 code indicates the API did receive your data, and that the data passed basic validation checks. Normally, your data will be available for querying within a few seconds. However, New Relic runs additional validation asynchronously after receiving your data. If you receive a 202 response but can't find your metric, this indicates that New Relic found an error during this asynchronous validation.

You can find these errors in the NrIntegrationError event in the account associated with the Insert API key you used. The requestId for each request will be tagged on the NrIntegrationError event. See Troubleshoot a NRIntegrationError event for more information.

The Metric API can return the following HTTP status codes:

Status code Definition
202 Data accepted.
400 Structure of the request is invalid.
403 Authentication failure.
404 The request path is incorrect.
405 Used a request method other than POST.
408 The request took too long to reach the endpoint.
411 The Content-Length header wasn’t included.
413 The payload was too big. Payloads must be under 1MB.
414 The request URI was too long.
415 The Content-Type or Content-Encoding was invalid.
429 The request rate quota has been exceeded.
431 The request headers are too long.
5xx There was a server error (please retry).

For more help

Recommendations for learning more:

  • Browse New Relic's Explorers Hub for community discussions about New Relic's APIs.
  • Use your preferred search engine to find other New Relic resources.