Metric naming reference

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.

support metric name syntax.png
The Metric name consists of a prefix, category name, label, and optional units indicator.

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.

Naming guidelines

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
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.

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.

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. Here are some examples:

Component/Disk/Bytes In/dev001
Component/Network/External services/

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]

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:

Recommendations for learning more: