Metric data for the Plugin API

This document supplements the authentication and compression requirements for the API for New Relic Plugins. The metric timeslice data is sent 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 New Relic's 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 across New Relic Plugins. When creating a plugin, you are responsible for managing your own GUIDs to avoid naming conflicts. For more information, see The parts of a plugin.

Time periods for metrics

Metrics that appear in dashboards are reported with a duration. The end time is implied by the time New Relic Plugins 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. Currently, 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. Be aware that New Relic Plugins does not extrapolate data values between the data points delivered. For example, New Relic Plugins will aggregate when there is too much data, but does not extrapolate 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.

Tip: 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.
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 Plugins.
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. For additional details, see Timeslice metric values in this document.
Agent data One of two required keys at the top level. A hash specifying information about the agent that is reporting data to New Relic Plugins 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.

Note: When graphing metrics, be aware that currently null = zero.

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.

Note: Currently 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

New Relic Plugins can do limited mathematical calculations 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).

Note: 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

Metrics example:

  "metrics" : {
    "Component/Database/Primary[Queries/Second]" : {
      "total" : 25,
      "count" : 2,
      "min" : 10,
      "max" : 15,
      "sum_of_squares" : 325
    },
    "Component/Database/Secondary[Queries/Second]" : [25, 2, 10, 15, 325],
    "Component/Database/Backup[Queries/Second]" : 10
  }

cURL example:

  curl -vi https://platform-api.newrelic.com/platform/v1/metrics \
    -H "X-License-Key: YOUR_LICENSE_KEY_HERE" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST -d '{
      "agent": {
        "host" : "db.internal.your_company.com",
        "pid" : 1234,
        "version" : "1.0.0"
      },
      "components": [
        {
          "name": "Primary MySQL Database",
          "guid": "com.your_company_name.plugin_name",
          "duration" : 60,
          "metrics" : {
            "Component/ProductionDatabase[Queries/Second]": 100,
            "Component/AnalyticsDatabase[Queries/Second]": {
              "min" : 2,
              "max" : 10,
              "total": 12,
              "count" : 2,
              "sum_of_squares" : 104
            }
          }
        }
      ]
    }'

For more help

Recommendations for learning more: