How New Relic Plugins works with plugin data

New Relic Plugins requires data to be sent in a particular format. All plugin metrics must be an integer or float, and they must be reported along with a duration. You can also report the type of metric so it can be converted from one unit type into another. When developing your plugin, follow the guidelines in this document.

You can display the metrics you collect in a variety of value methods, including throughput, averages, min/max, and rate. The metrics appear in charts and tables you create for your plugin's user interface.

Use integers and floats

Because New Relic Plugins is designed to report on frequency metrics, all metric data should be non-negative integers or floating-point numbers:

  • Non-negative integers: Supported.
  • Floating-point numbers: Supported.
  • Negative values: Not supported, except for summary metrics on the plugin's Summary page. Otherwise, the UI shows negative values as zero.
  • String values: Not supported; the UI shows strings as zero. However, parts of your metric name (the key) can be displayed in the UI.

Define the time period (duration)

All metrics must include a duration period that starts no more than a few hours in the past. The end time is set automatically to the time New Relic Plugins receives the metrics. You cannot report a duration that starts or ends in the future, or a duration that ends in the past.

For best results, use one of the plugin SDKs to create your plugin. Otherwise, some POST attempts may fail because the actual recorded duration could vary in increments of the plugin's scheduled reporting frequency.

Follow unit conversion guidelines

New Relic Plugins automatically converts some units (such as rate units) to more natural forms. For example, [bytes/second] is converted to Bps.

Follow these guidelines for unit conversions:

  • Long format: Always specify the long format (for exmaple, [bytes/second]) in the metric name. New Relic Plugins will use the long or short version as appropriate. (Unit designations are not case sensitive.)
  • Consistency: Use modifiers consistently in the metric name. If you use a different modifier with the same metric name, New Relic Plugins will treat it as a different metric.
  • Optional: Standard modifiers: Provide standard modifiers to the first metric in a value unit. For example, rather than specifying [bytes/second], you can specify [kiloBytes/second].

Plugins accepts these standard modifiers:

Modifier Multiplier Modifier Multiplier
Kilo 1000 --- ---
Mega 1000^2 --- ---
Giga 1000^3 Gibi 1024^3
Tera 1000^4 Tebi 1024^4
Peta 1000^5 Pebi 1024^5

Select value methods for display in the UI

When you define a metric value for reporting, New Relic Plugins also captures a count, min, max, and sum of squares. Depending on whether you report single or aggregate values, you may report these numbers directly, or Plugins may calculate them automatically. You can then choose a value method for rendering these metrics in your plugin UI.

In general, to configure value methods in the user interface:

  1. Select the metric you want to use.
  2. Review the list of value methods to select how to present the data in a column or plotted in a chart.

Available value methods depend on the format of the units part of the metric name:

Value method Count | Value Value Rate

Count:

The total of the count field over the entire timeslice data interval. When aggregating timeslice data, the count is summed.

[check icon] [check icon]

Total value:

The total value over the entire time slice data interval. When aggregating timeslice data, the value field is summed

[check icon] [check icon] Time rates only

Average value:

The total value divided by the total count, calculated only when units for both count and value are available.

[check icon] [check icon] [check icon]

Throughput:

The total count divided by the time interval of the time slice. By default New Relic Plugins measures the throughput in minutes according to the count units, such as calls per minute or bytes per minute. When the count units are specified in time (seconds), then the throughput appears as a percentage.

[check icon]

Min/Max:

The statistical values for minimum and maximum values when recorded in the metric value along with Count and Value.

[check icon] [check icon] [check icon]

Standard deviation:

The standard deviation of the entire set of measures recorded over the time interval. This is available only if the sum of squares field was populated in the metric value. The sum of squares and mean are used to calculate the standard deviation. In practice, this is meaningful only for populations that resemble a normal distribution.

[check icon] [check icon] [check icon]

Rate:

The rate is the total value divided by the time interval. When units of the value are in time, then the rate value is a percentage value. Units that are themselves rates will not have an explicit rate value method. The rate is simply the average value.

[check icon]

Percentage:

If you want the metric to appear as a percentage in the user interface, then you must define it as a percentage in the JSON.

For more help

Additional documentation resources include:

Recommendations for learning more: