• /
  • Log in
  • Free account

Metric data for the Plugin API

Limited access

Important

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.

Limited access to legacy plugins

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.

URI

Metric timeslice data is sent with the Plugin API as an HTTP POST of JSON data using this URI:

https://platform-api.newrelic.com/platform/v1/metrics

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).

GUID

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.

Time periods for metrics

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.

Metric data details

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 host and version are required.

When graphing metrics, be aware that null = zero.

Metric data POST

Description

Component data

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:

name

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.

guid

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.

duration

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.

metrics

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.

Agent data

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.

host (required)

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.

pid (optional)

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.

version (required)

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.

Timeslice metric values

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

Description

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:

  • Total value over the time period
  • Count of the number of events this value represents over the time period; the average is calculated by dividing total by count
  • Minimum value over the time period
  • Maximum value over the time period
  • Sum of squares for the samples over the time period

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:

  • total: Total value over the time period
  • count: Count of the number of events this value represents over the time period; the average is calculated by dividing total by count
  • min: Minimum value over the time period
  • max: Maximum value over the time period
  • sum_of_squares: Sum of squares for the samples over the time period

Calculations

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.

Examples

Here are some examples.

Metric references

Refer to these references as you develop your own plugins.

For more help

If you need more help, check out these support and learning resources:

Create issueEdit page
Copyright © 2021 New Relic Inc.