This document describes the schema for custom metric values used by the API for New Relic Plugins.
Single and aggregate values
When reporting a metric value, it can be reported in one of two ways:
- As a single value, which is typically the Value being reported for that time slice. If you are using an SDK, you report the single value to the SDK. It handles tracking the rest of these values.
- As a set of aggregate values that includes the Min, Max, and Sum of Squares values for the Value being reported. If you are developing the plugin with 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 for New Relic Plugins, this is done automatically. If you are using the Plugin API to develop plugins, you will need to code for this.
Metric value fields
A metric value contains several fields, but is represented primarily by the Count and Value. Count is a 32-bit integer field, and Value is a 32-bit float. Metric values can represent more than one data point or sample as an aggregation of measures. Typically Count is the number of samples, and Value is the total value of all samples, but that is not always the case. For more information, see Metric naming examples.
Here are the fields in a metric value:
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.|
The minimum and maximum values when the count is > 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.
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.
For more help
Additional documentation resources include:
- How New Relic Plugins works with plugin data (metric guidelines, values, and unit conversions
- Plugin API specification (overview of authentication, compression, and metric data POST)
- Metric naming reference (name format, segment order, style guidelines, and attributes for metrics)
- Metric units reference (metric unit guidelines, defining units for both values and counts)
- Metric data for the Plugin API (metric time periods, data details, timeslice data values, calculations)