Plugin API specification

The API for New Relic Plugins supports one operation, a POST of metric data. New Relic Partners and customers can use this API to send their own metric data to New Relic Plugins and view data received from the API in the New Relic Plugins user interface.

To enhance the presentation of your metric data, use the plugin developer tools in the New Relic Plugins application to develop customized dashboards. For more information, see Working with plugin dashboards.

Contents

Authentication

Requests are authenticated using the X-License-Key request header, which is set to the account license key.

Compression

Data can be sent in the following encoding formats:

identity

deflate

gzip

If data is sent compressed, make sure the Content-Encoding header specifies the type of encoding.

POST frequency and limitations

The New Relic Plugins product is designed to receive a continuous stream of metrics at a certain maximum speed, and to present this information on useful charts. The recommended frequency for sending data to New Relic Plugins is to send 60 seconds worth of data once a minute. Agents sending data more frequently than twice a minute on average may be subject to enforced limits on the number of metrics being saved.

The following are recommended soft limits. Requests smaller than this will work; requests larger than this are subject to rejection or automatic data aggregation. As a hard cap, the total size of the POST payload should be no larger than 1MB.

Type

Limit

Description

Components

500

Number of distinct components currently tracked. Please note this is a per POST limit only. More than 500 components are able to report to an account simultaneously.

Metrics per component

10,000

Total number of unique metrics per component. Take precautions to ensure metric names are not generated too dynamically. Even if the number of metrics being sent in each individual post is small, over time they may add up to a large number of unique metrics. When the number of metrics for a given component exceeds this limit, the server may start aggregating metrics together by globbing segments of the metric name with an asterisk (*).

Metrics per post

20,000

Number of metrics sent per post. A post may send data for multiple components in a single request as long as the total number of metrics in the request does not exceed this limit.

Frequency of post

2 per minute

Frequency of update. Agents are expected to send data no more frequently than 1 per minute.

If the metric is "expensive" to calculate and does not change quickly, consider writing your plugin agent so that it skips some polling cycles to retrieve data and then sends the last value. This produces better results for your plugin users' dashboards.

REST API

At this time, the Plugin API does not support New Relic's REST API, and vice versa. However, you can use New Relic's REST API (v2) to extract plugin data. For a list with links to procedures and examples, see Plugin Examples (v2).