Transition to New Relic subscription usage system

On July 10, 2018, New Relic released a new, improved system for New Relic owners and admins to monitor their subscription usage data. This includes new UI displays, and new Insights events and attributes that can be analyzed via NRQL queries or retrieved via the Insights query API.

This guide will walk you through the major changes between the old usage tracking system and the new one, and give you tips for switching to the new system.

The new usage UI replaces the older UI. In addition, the Insights API replaces the deprecated usage-related REST APIs.


The new usage system gives you helpful features for understanding how your organization is using New Relic products. You can:

  • Go to a single page in the UI to see overview charts for all your product usage.
  • See product-specific UI pages with more usage details.
  • View and filter usage chart data in several ways, like by accounts, applications, and hosts.
  • Track usage by account hierarchy (master account, sub-account, partnership) more easily.
  • Get focused data using Insights NRQL queries or the Insights query API.
  • Make customized usage charts in Insights.

The underlying billing logic has stayed the same; the main change is that your usage is easier to understand and easier to retrieve details about. Aside from the unit of usage measurement, which differs by product, the UI charts and features work mostly the same for all products.

One major change for Insights Pro users is that Insights usage charts now display only the Insights events that count towards a paid subscription. Events that are included as part of other New Relic product subscriptions are not displayed.

Get started

Here are some recommendations for getting started using the new usage system and getting the most out of it:

  1. If you use New Relic APM and have an environment with Docker or other Linux containers, or if you use Infrastructure with an AWS EC2 environment: upgrade your agents to at least the versions below. This will ensure you benefit from the improvements in tracking usage in these environments.

    APM with Docker or Linux containers

    If you use Docker or Linux containers (and are not exclusively using AWS EC2 for compute instances), upgrade your APM agent to ensure it supports the improved host usage calculations:

    APM with AWS EC2

    If you use New Relic APM with an Amazon EC2 environment, upgrade to an APM agent that supports the new host usage calculations (note these are earlier than the Docker/container agent versions).

  2. Play with the new usage UI: From, select the account dropdown, select Account settings, then select Usage. Look at the usage charts, and filter and group your usage data in different ways.
  3. Read the Introduction to usage data documentation. You'll learn details about the UI features, how you can create custom Insights queries and charts of your usage data, and how you can query the new data with the Insights query API .
  4. Switch to the Insights query APIs for your selected product. The previous REST API calls are deprecated.

Changes in features

Some of the new reporting capabilities may result in changes to how New Relic calculates or reports your product subscription usage:

APM may display different host names

New Relic has improved how hosts in Linux container environments and cloud providers are identified and counted. As a result of this improvement, the host names shown on the APM Usage UI page will sometimes not match the host names shown elsewhere in APM. Both host names are recorded in the subscription usage data available in Insights, so you can translate between the different identifiers.

New Relic must identify unique physical hosts or VMs, so the usage calculations no longer use these names to identify hosts:

  • DNS names (which can represent multiple hosts or VMs)
  • Dynamic names provided in container environments (which can represent single containers running alongside many others on a single host/VM). These include Docker container IDs or Kubernetes deployment IDs.

This is why the usage calculations often use a machine-generated host ID that APM agents use to uniquely identify the single copy of the operating system running on your host or VM. For example, Docker, Kubernetes, and AWS environments commonly use these machine-generated IDs.

To ensure your account has accurate usage calculations for Docker (and other Linux containers) and AWS EC2, see Getting started.

Insights Pro changes

For Insights Pro, the usage UI will now display only the Insights events that count towards a paid Insights subscription, making it easier for you to understand your usage.

You may see some Insights Pro usage numbers have changed. This is because usage display is now more accurate with respect to varying retention periods and Mobile data types.

Heroku: Potential increase in reported APM usage

Previously the APM usage calculation used the agent-reported hostname to identify hosts. For Ruby and Python apps running on Heroku, by default, the hostname was configured in the New Relic agent to be the human-readable name of the Heroku dyno (app instance).

APM usage calculations now ignore the dyno name and, instead, the calculations use the operating system's instance name (Linux boot ID) to distinguish hosts in Heroku. This is why Heroku customers billed directly by New Relic (as opposed to customers billed for New Relic through Heroku) may see an increase in reported APM host or CU usage.

In this case, contact your New Relic account representative to clarify usage and billing terms.

For more help

Recommendations for learning more: