Metric data for the Plugin API

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.

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.

Metrics
  "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
            }
          }
        }
      ]
    }'

Metric references

Refer to these references as you develop your own plugins.

Metric naming guidelines

Metric timeslice data uses a unique case-sensitive identifier, referred to as the metric name. In order for the metric to be rendered usefully in the user interface, the metric name must contain a prefix, category name, label, and optional units indicator.

Here are some recommended guidelines for the text in metric names to make them more readable in the user interface.

Metric naming guidelines Guidelines
UI display

Use case and whitespace characters appropriate for display in the user interface, because segments are rendered as-is in the UI.

Category and label segments

Metric names are case sensitive.

  • Capitalize the first word in the category and label segments.
  • Keep category and label segments as short as possible.
Length

There is a limit of 255 characters for metric names.

Characters to avoid using

Avoid using the following characters in names. These characters have special meaning and should not be used except where specifically required for their purpose.

  • /
  • ]
  • [
  • |
  • *

Also avoid multi-byte characters.

Units

Use abbreviated names for units when possible.

Metric segments

Each of these segments is divided by the forward slash / character. Each segment is interpreted for a specific purpose in the UI and roughly follows this pattern:

prefix/category/label[units]

For example, the metric representing the latency of cache hits reported by a plugin collecting data for a cache appliance might look like this:

Component/Cache/Hits[sec|hit]
Metric segment order Notes

Prefix:

Component/ or Custom/

The first segment of a custom metric is Component/ (if it comes from a plugin agent) or Custom/ (if it is a custom metric collected by a New Relic agent. For example, Custom/MyMetric).

If you use the Plugin API only, and if the metrics do not start with Component/, they may not be available or may not appear correctly in charts and dashboards.

Category name The second part of a custom metric is a category name, used to group metrics into different categories. For example, the metrics reported by a database plugin may fall into categories such as schema, tables, or connections.
Label The third part of the metric name is used for labeling the data when it appears in tables and charts. If it contains multiple segments, each slash separating the segments of the label will be rendered as part of the label.
Units The fourth segment of the metric consists of a units specification.
Metric attributes

Most metrics are defined statically and represent some global state; for example, cache size. Other metrics are dynamic and include some contextual attribute like the name of a host or a file. These metrics need to be structured so you can easily show them as a group in a table stacked in a chart.

To add attribute names to a metric, put them in trailing segments separated by a forward slash / character. For example:

Component/Disk/Bytes In/dev001
Component/Network/External services/ae592c3.aws.com

You can specify more than one attribute as long as they occupy the same position for a given metric category and label:

Component/Tables/Row count/DB001/BLOG_POSTS[rows]

Avoid overloading the metric space by putting in segment values that have a large range of values.

While something like a customer's region in an attribute is a reasonable thing to track in the metric, the customer name would not be if you have more than a few hundred customers. If your agent starts sending an excessive amount of metrics, your metrics may be automatically collapsed into groups with wildcards:

Component/Users/*[visits]
Metric values

You can report a metric value in one of two ways:

  • Single value: This typically is the value being reported for that time slice. If you use an SDK, you report the single value to the SDK. It handles tracking the rest of these values.
  • Set of aggregate value: This includes the min, max, and sum of squares values for the value being reported. If you use the Plugin API, the preferred method is to report all of the values.

When aggregating a series of timeslice data into a single timeslice data entry for a given period, all fields are summed except for the min and max value. If you are using an SDK plugins, this is done automatically. If you are using the Plugin API to develop plugins, you need to code for this.

A metric value contains several fields, but it is represented primarily by the count and value. The count is a 32-bit integer field, and the value is a 32-bit float. Metric values can represent more than one data point or sample as an aggregation of measures. Typically the count is the number of samples, and the value is the total value of all samples.

Here are the fields in a metric value:

Metric value Description
count

The number of things being measured. If data is collected at the time the event occurs, like with some kind of injection, then the count in the timeslice data will be 1.

Required if it is not 1 (0 generally represents an absent value).

value Required: The total value measured across all things being counted. When averages are calculated later, we divide the value by the count. In some cases, the value field is irrelevant.
min, max

The minimum and maximum values when the count is greater than 1. When the count is 1, these are the same as the value.

Optional depending on whether they are available or relevant for a given metric.

sum of squares

This is the sum of squares of each value and is useful when the values follow a standard distribution. You can only capture this value when you are collecting data each time the event happens. You store the value of the event in the value field and the square of the value in the sum of squares. This is used to calculate a standard deviation later on.

The sum of squares is optional. It is used to calculate a standard deviation for a selection of data. If standard deviation for the value is not meaningful, such as when the values are not part of a normal distribution, then the sum of squares is omitted.

Units

When a metric value is collected by periodically sampling an interface, the count units are implicitly samples, and the value units are whatever is being sampled. For data it might be bytes. For throughput it might be something like kilobytes/second. For utilization (like CPU) it might be percent. When the count units are samples, they can be omitted in the metric name.

Units of time, bytes, and bits may get special treatment, allowing additional conversion in the user interface between magnitudes. For example, if you specify a metric with units of kilobytes, then in the UI you may be presented the option of displaying a chart of Mb.

Metrics units describe what the value field and count represent. Units are specified inside brackets and consist of units for the value, followed by a pipe (|) and then the units for the count. For example:

Component/metric_id[value_unit|count_unit]

Exception: The pipe and count units (|[count_unit]) are not required after the value unit for samples.

Rate metrics are commonly defined as sample per interval. This is defined as units/interval in the metric, with a forward slash to separate units from interval. For example:

Component/metric_id[value_unit/interval]

In rare cases there will only be a unit value for count. The value will be interpreted as unitless. Value units are omitted, and the vertical bar appears in front of the count units. For example:

Component/metric_id[|count_unit]
Units for plugin metrics Notes
Naming conventions

You can have mixed-case unit names. They.can consist strictly of alphabetical characters as well as the _, %, or / symbols. Case is preserved. Punctuation markers, dashes, spaces and any other symbols are not allowed.

Recommendation: Use uncapitalized words, spelled out in full. For example, use second not sec.

Rate metrics

When a metric value represents a rate, such as bytes/second, then the value is assumed to be a sample for the given interval. The units specifier looks like [bytes/second] since the count units are implicitly samples. For example:

Component/metric_id[bytes/second]

The count units are samples (default) and the value units are bytes/second. The forward slash separates the units from the interval.

Count with units

A common case for declaring units is when measuring response times. If the custom metric represents the average latency of a call to a cache, then the units for the metric value are seconds per call. For example:

Component/metric_id[seconds|call]

Count units are calls and value units are seconds. The default count metric is not being used, so you need to specify it. The bar separates the value units from the count units.

Units in charts

The units specified in a metric have several implications for the way the values are interpreted by generic charts and tables:

  • Units display in labels and tooltips in charts to indicate what the values represent.
  • Units imply a set of different values available from a single metric value.

When creating a chart in a dashboard, the dashboard author selects one of the available value methods for that metric to plot in the chart.

For more help

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