For an even better experience than plugins, go to:
- newrelic.com/integrations: Integrate the on-host and cloud systems you already use with New Relic, so you can filter and analyze data, create dashboards, and set alerts within a single platform.
- developer.newrelic.com: Use developer tools to collect data from any source, automate workflows, build apps, and use our APIs.
As of December 2, 2020, plugin access has been limited to accounts that have accessed a legacy plugin in the past 30 days. The legacy plugin experience will reach end of life (EoL) as of June 16, 2021. For more information, see our Explorers Hub post.
Metric timeslice data is sent with the Plugin API as an HTTP POST of JSON data using this URI:
The Plugin API does not support New Relic's REST API, and vice versa. However, you can use the REST API (v2) to extract plugin data. For a list with links to procedures and examples, see Plugin examples (v2).
The plugin needs a Globally Unique Identifier (GUID), which is a character string limited to no less than 4 and no more than 255 characters. The GUID for a published plugin must be unique for each plugin. When creating a plugin, you are responsible for managing your own GUIDs to avoid naming conflicts.
Metrics that appear in dashboards are reported with a duration. The end time is implied by the time New Relic receives the metric(s). Thus, you cannot define metric values that both start and end in the future, or start and end in the past.
The Plugin API is designed for live metrics only, not historical metric collection. Metrics may only be reported for a period starting in the past (no more than a few hours) and ending upon reporting.
The charts on your plugin's dashboards can show any time period you want; for example, 30 minutes, 30 days, etc. You can also deliver data at 1-hour intervals. New Relic does not extrapolate data values between the data points delivered. For example, data will aggregate when there is too much, but data will not be extrapolated if there is not enough data. In order for data to appear on a 30 minute chart, make sure at least one data point is within the range, or no data will appear.
Use a 60-second polling interval, because the default dashboard shows 30 minutes of data, which gives 30 data points for the chart. Or, if you want to show 3 days of data, use a 1-hour polling interval, which provides 24*3=72 data points for your chart.
The JSON data is a hash with two required keys at the top level:
components: An array of components, each consisting of a hash of attributes for the individual component, including the metric data.
agent: A hash describing the agent that is reporting metrics data to New Relic Plugins on behalf of the component(s). Of these values, only
When graphing metrics, be aware that null = zero.
Metric data POST
One of two required keys at the top level. This is an array of hashes describing the components that report metrics in this request. Each hash contains the following values:
A name (<=32 characters) that uniquely identifies the monitored entity and appears as the display name for this agent. Note: Metric names are case sensitive.
A "reverse domain name" styled identifier; for example, com.newrelic.mysql. This is a unique identity defined in the plugin's user interface, which ties the agent data to the corresponding plugin user interface in New Relic.
The duration in seconds over which the metric data was collected. The end time is implied as the time the data is received by the API.
Timeslice data for each metric being reported. The hash keys are metric names, and the values are the timeslice data value for the named metric.
One of two required keys at the top level. A hash specifying information about the agent that is reporting data on behalf of the components.
The hostname of the agent monitoring the specified components. This is the hostname where the monitoring agent is running, not the hostname of the component being monitored.
The process identifier of the agent monitoring the specified components. This is the process identifier of the monitoring agent itself, not a process identifier that may be associated with the monitored components.
The version of the agent monitoring the specified components, using the format A.B.C where A, B, and C are integers. The version number must conform to the rules specified in standard Semantic Versioning scheme v2.0.0.
Metrics are sent inside the
component hash with the key
metrics and a hash as a value. The hash keys are metric names, and the values are the timeslice data values for the named metric. The
timeslice hash value uses one of three formats:
Timeslice hash value
A single scalar value with a floating point number or integer
This is the simplest format, and this number is required. The reported value is used as the total, minimum, and maximum data value. The count value is assumed to be 1.
The Plugin API does not support reporting of arbitrary string metrics, only scalar values that are aggregated.
Array of five required values in specific order
An array of five required integers or floating point numbers that represent, in order:
Hash with five required key/value pairs in any order
A hash with value names as the keys, and integers or floating point values as the values. All five key/value pairs are required. The keys of the hash are the type of timeslice data, and the value is the data value. These has key/value pairs can be in any order:
Limited mathematical calculations are available with the key/value pairs, such as computing total, count, minimum, maximum, averages, and standard deviations. However, to do more extensive calculations, you need to do the math in the agent, and then send the results as a new metric. For example, send Metric1, Metric2, and Metric3 (which equals Metric1 divided by Metric2).
If you submit negative metric values, the charts on your plugin's dashboards will not show them. However, the summary metrics for your plugin will show negative values.
Here are some examples.
Refer to these references as you develop your own plugins.