Metric timeslice data uses a unique case-sensitive identifier, referred to as the metric name. The metric name's format must follow certain conventions in order for the metric to be rendered usefully in the user interface for New Relic Plugins. This document describes the schema for custom metric data used by the API for New Relic Plugins. For additional information, see Metric naming examples.
Metric segment order
Metric timeslice data consist of segments divided by the forward slash
/ character. Each segment is interpreted for a specific purpose in the UI and roughly follows this pattern:
For example, the metric representing the latency of cache hits reported by a plugin collecting data for a cache appliance might look like this:
|Metric segment order||Notes|
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 Java or Ruby agent (for example, Custom/MyMetric).
If you use the Plugin API only, be aware that metrics that do not start with Component/ may not be available for dashboard charts and/or may not appear correctly in charts.
|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. For more information, see Metric value reference.|
Here are some recommended guidelines for the text in metric names to make them more readable in the New Relic Plugins user interface.
|Metric naming guidelines||Guidelines|
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.
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.
See the Metric value reference for information about naming and formatting units. Use abbreviated names for units when possible.
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. Here are some examples:
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:
Beware of 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, New Relic Plugins may automatically start collapsing the metrics into groups with wildcards:
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 data for the Plugin API (metric time periods, data details, timeslice data values, calculations)
- Metric naming examples (practical examples of custom metric naming guidelines used by the API for New Relic Plugins when creating plugins)
- Metric value reference (metric value guidelines, required and optional fields, aggregation)
- Metric units reference (metric unit guidelines, defining units for both values and counts)
- Plugin API responses and error codes (details about debugging logs and error code values)