Labels and categories: Organize apps and monitors

You can label and organize entities monitored by New Relic so they roll up into an unlimited number of meaningful categories, including:

  • Apps in New Relic APM
  • Monitors (such as ping monitors or scripted browser monitors) in New Relic Synthetics

This lets you easily sort, filter, and page through them from their product index pages in the New Relic UI.

For more information, check out New Relic University’s tutorial Organize your data with categories and labels. Or, go directly to the full online course Get started with APM.


By creating labels for categories and their values, and then rolling up your entities into specific categories, you can identify useful groups. This makes it easier to find, view, and compare only the entities that are meaningful to you. You can also see the comparative health status for categories (and the entities within the categories) at a glance.

Labels and categories
APM > Applications list > (selected category): This example shows five labels "rolled up" in the Environment category: Dev, Integration, Production, Staging, and Test. The colored bar below each label shows the overall health status, and colored squares within the label show the individual apps' comparative health status at a glance.


Permissions to maintain categories and labels depend on your New Relic role and the selected product.

  • APM: You must be the account Owner or Admin.
  • Synthetics: Any role within the account can create, update, and delete categories and labels within the New Relic Synthetics UI. However, you must be the account Owner or Admin to use the REST API to maintain labels and categories for Synthetics.

Guidelines for category labels

Follow these guidelines for creating labels for your categories.

Labels Guidelines
Number of categories Create as many unique labels as needed for meaningful categories. Your entities monitored by New Relic can have from zero to an unlimited number of categories.
Label format Type the category name, a colon :, and the value; for example, Environment:Dev, Environment:Production, Tier:Front_End, Test:Mobile, etc. Always include a colon : between the category name and its value.
Valid characters For category names and their values, only use letters, numbers, hyphens, or underscores. Do not use any spaces or other special characters.

Once a category name is used, the capitalization of that term will persist for that entity. For example, once "environment" is used, any attempt to use Environment will default back to environment.

Use upper-case letters for the first letter of the category name and value. If you want other letters to be capitalized, include a dash (hyphen) - or underscore _; for example, Tier:Front-End.

New Relic treats the colon (required) and optional dashes as word breaks for changing case. You can search using upper-case or lower-case letters.

When you create a label from the user interface, New Relic automatically changes the first letter and the letter after a dash to uppercase. New Relic also changes any other upper-case letters to lower case. For example, if you create the label Label-cAtegory:lABEL-value, New Relic automatically saves it as Label-Category:Label-Value.

Create labels and categories

Labels and categories
APM > Applications index: Here is an example of the process to create category labels, add apps to categories, and select a category to view summary and detail information. Follow a similar process from the Synthetics > Synthetics index.

APM: Owners and Admins

Synthetics: Any role

To add an entity monitored by New Relic APM or Synthetics to one or more categories, assign a meaningful label to the category first. You can create as many labels for an entity as needed. You can also assign an unlimited number of entities to a category.

  1. Go to, and select APM or Synthetics.
  2. From the index, select Show Labels > On.
  3. To assign an entity to a category, select the plus plus-circle icon by its name.
  4. Follow the guidelines to type the label; use the format Category:Value.
  5. To save the new label, press Enter or Return.

Use the REST API

Owners and Admins

You can use New Relic's REST API to manage labels and categories. This is useful, for example, if you need a list of existing labels, or if you want to change a label by deleting the existing label and creating a new label.

View categories and labels

After the labels are created and the entities are assigned to one or more categories, New Relic rolls the entities up into their categories. This makes it easy to view selected categories of applications or monitors.

To view a category or label, or to view entities assigned to them:

  1. Go to, and select APM or Synthetics.
  2. From the selected New Relic product's index, use the search search field to type the category's or label's name as a partial or exact match, or select it from the list.
  3. Use the available tools to view summary information about entities in the category or to drill down into detailed information about a specific entity.

The rollup view lists the total entities in the category and the number for each health status. The color-coded bar below the category name also summarizes the overall health status. For example, if any entities in the category are not reporting data, the colored bar will include gray.

Labels are not available for the Transaction event type and cannot be used in NRQL queries.

Remove a label from an entity

APM: Owners and Admins

Synthetics: Any role

To unassign a label from an entity:

  1. Go to, and select APM or Synthetics.
  2. From the selected New Relic product's index, select Show labels > On.
  3. Select the label you want to remove for the entity, and confirm your choice.

To reassign the label, follow standard procedures to create labels and categories.

Change or delete labels

Owner and Admins

You can use the New Relic user interface to remove a label from an entity, but you cannot use the UI to permanently delete a label. Instead, use the API to delete a label:

Also, you cannot change a label's name. Instead, use the API to delete the existing label and create a new label.

Maintain with agent config file settings

If you want to use your New Relic agent's configuration file to maintain label settings for applications, make sure you are using a supported release. For more information, refer to the configuration documentation for your New Relic agent.

  • Java: 3.15.0 or higher
  • .NET or higher
  • Node.js 1.12.1 or higher
  • PHP 4.14 or higher
  • Python or higher
  • Ruby 3.9.2 or higher

For more help

Additional documentation resources include:

Recommendations for learning more: