Use tags to help organize and find your data

In the software industry, a tag typically refers to a piece of metadata added to a data set for the purpose of improving data organization and findability.

At New Relic, our tags are key:value pairs (like team: operations) added to various sets of data, like monitored apps and hosts, agents, dashboards, and workloads. We make some important attributes available as tags (for example, app metadata like app name and language, and host metadata like host name and AWS region). And you can also add your own custom tags.

You can use tags in the UI to filter down to relevant data, as shown here:

New Relic filtering workloads using tags
Here you can see an accountId tag being used to filter workloads for a specific account.

You can use tags to:

  • Help organize data coming from a large number of sources and/or to a large number of New Relic accounts
  • Identity teams, roles, environment, or regions to know who’s responsible for what (see example use cases)
  • Better organize and search dashboards and workloads

Tags are useful for organizing data at a high level. If you wanted to add more fine-grained detail, like capturing user names or other high-cardinality values, custom attributes or custom events would be a better solution.

At New Relic, tags were previously called "labels." You may sometimes see "label" used in our code; for example, some of our APM agent config files use a label config option for tags.

Keep reading to learn more about tags.

Tag format and limits

Format requirements and limits for tags:

  • The UI has limits on the total number of tags it can display per entity:
    • Limit of 100 for tags reported by default or added via agent/integration configuration.
    • Limit of 100 for custom tags added via UI or API.
  • The following are maximum character length for tags:
    • Key: 128 characters
    • Value: 256 characters
  • When using our API to add tags, a dash (-) in a tag key is interpreted as a minus symbol. If your tag key has a dash, use back ticks around it (like `key-name`).

Best practices and tips

Before adding tags, we recommend first seeing how our default tags work for you. When you're ready to add your own tags, read the best practices below to get the most out of them.

Tips on keeping tags simple:

  • Start by adding only tags you know you’ll definitely use. Unused tags create noise and may add confusion.
  • Try to use short tags. Shorter tags are easier to parse, and also the UI may sometimes truncate longer tags. (See character limits.)
  • When possible, use keys and values that are human-readable (for example, region: EMEA is better than Param8323 : 1229072).
  • Avoid including several values like regions: EMEA | US | LATAM in a single tag. We recommend using three different tags for that, like region: emea, region: us, and region: latam. If you want to match multiple tags, you can do that using the advanced options in the filter UI.

Tips on using tags consistently:

  • Try to be consistent with tag language across your teams and entities.
  • Be consistent with naming. For example, avoid using both region: emea and reg: emea.
  • Be consistent with format. For example, avoid using both camelCase and kebab-case.
  • Be consistent with capitalization. For example, avoid using both env: staging and env: Staging (although tag searching is case-insensitive in the UI and API)

Tips on cross-team implementation:

  • One reason for using tags is to improve observability and cost allocation. For this reason, responsibility for tag implementation is often assigned to an observability team, SREs, a group of architects, or a cross-team task force.
  • We recommend the people responsible for implementing tags meet and create an internal policy to describe how the tags are defined and which conventions are to be used. Keep this reference manual up-to-date.
  • Automate the definition of tags when you deploy New Relic agents, at the cloud provider, or through New Relic automation tools, such as the API or Terraform.
  • Create recurring reports that identify entities that are non-compliant with your tagging standards.

Tag examples

Here are some examples of common ways to use tags to organize data:

Team-related tags

Creating tags for team names can be helpful to understand which team, group, department, or region was responsible for a change that led to a performance issue.

Team examples:

  • team: backend
  • team: frontend
  • team: db

Role examples:

  • roles: architecture
  • roles: devops
  • roles: pm

Region examples:

  • region: emea
  • region: america
  • region: asia
Environment-related tags

You can create entities for the environment they belong to. Examples:

  • env: production
  • env: qa
  • env: development
  • env: staging
Criticality-related tags

You can create tags related to criticality levels, which lets you easier track the most critical issues.


  • layer: level1
  • layer: level2
  • layer: level3

How tags are added

Some important attributes, by default, are available for use as tags. For example, the account name, the account ID, and some basic host/server metadata are available as default tags. You can't remove these available-by-default tags.

Here are some details about how tags are added for some specific data sources:

Add tags via UI or API

When you add tags via the UI or API, this occurs at the entity level. This means that, for example, if you have multiple APM agents monitoring a single entity and apply a tag via the UI, that tag is available for all data coming from that entity.

To add or delete tags via the UI:

  1. Select a monitored entity, like a monitored app or host.
  2. Near the entity’s name at the top of the page, select the See metadata and manage tags menu.
  3. In the menu that pops up, add or delete a tag.

To manage tags via API: see our NerdGraph tagging docs. For a guide to using our CLI to automate tagging, see our developer site.

APM agent tags

You can apply tags via the UI and API or you can add tags using APM agent configuration:

Infrastructure data tags

There are several ways tags are added to infrastructure entities and services:

  • Use the UI or API to add tags at the entity level.
  • Infrastructure agent: some attributes are available by default as tags. You can also add custom attributes, which are also available as tags in the UI.
  • On-host integrations: some attributes are available by default as tags. You can also add tags by using integration-specific labels config options (for an example, see the labels config for the Apache integration).
  • Cloud service integrations: by default we report tags and labels that are defined in the cloud service. To add tags, you'd add them on the cloud-service-side.

Use tags to filter the UI

New Relic advanced tag filter query
Use the filter field at the top of the entity explorer to filter down to the entities you care about. You can use multiple filter conditions.

To filter down to certain entities using tags:

  1. From, click Entity explorer.
  2. Click the Filter by... field to see a dropdown of available attributes and tags.
  3. You can filter by multiple elements and use advanced search options.

To find an entity’s metadata and tags from the UI, here are two options:

  • From a list of entities in the UI, at the far right, select an entity's ellipsis icon.


  • Select an entity. Near the top of the page, select the information icon.

To use the API to view tags, see our NerdGraph docs.

Learn about how to use tags with dashboards and how to use tags with workloads.

Custom queries and charts

As explained in Tag sources, some attributes are available as tags. You can query attributes and create custom charts using NRQL.

For more help

If you need more help, check out these support and learning resources: