Custom metrics

Custom metrics allow you to record arbitrary metric timeslice data via an API call. For example, you could report the value of each shopping cart as part of the checkout transaction.

Use the Insights Metric Explorer to search your custom metrics and create customized charts for them. You can use custom metrics to unify your monitoring inside New Relic.

Naming custom metrics

Start all custom metric names with Custom/ (for example, Custom/MyMetric/My_label). The Custom/ prefix is required for all custom metrics.


A custom metric name consists of the prefix Custom/, the category or class name, and a method or label, each separated with a slash.

Custom metrics allow you to report any metric that passes through your code. For example, New Relic uses custom metrics to monitor the annualized value of our current subscriptions. You could also use custom metrics to report shopping cart value, the number of items in a cart, or the number of active connections.

Implementing custom metrics

Implementing custom metrics requires API calls. The exact details of the API call vary by agent.

If you are testing your custom metric implementation, run the agent for at least 10 minutes to ensure that the API call is reported to New Relic.

New Relic agents:

  • Java: recordMetric
  • .NET: RecordMetric
  • Node.js: recordMetric
  • PHP: newrelic_custom_metric
  • Python: record_custom_metric and register_data_source
  • Ruby: record_metric and increment_metric

New Relic Mobile agent SDKs:

Grouping issues

Collecting too many metric timeslices can impact the performance of both your application and New Relic. For example, if you have thousands of individual users, avoid creating metrics to track the performance of their unique user IDs. This could result in such a large number of metrics that it becomes nearly impossible to navigate or make sense of the data. In this example, the best approach is to use a placeholder, such as an asterisk (*), instead of the user IDs.

When the total number of unique metric names exceeds 2000, limits begin to apply automatically that affect how data appears in the user interface, such as in charts and tables. For more information, see Metric grouping issues.

To avoid potential data problems, try to keep the total number of unique metric timeslices introduced by custom metrics under 2000.

For more help

In addition to the agent documentation noted above, documentation resources for using custom instrumentation include:

Join the discussion about New Relic APM in the New Relic Online Technical Community! The Technical Community is a public platform to discuss and troubleshoot your New Relic toolset.

If you need additional help, get support at