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). You can also add your own custom tags.
You can use tags in the UI to filter down to relevant data. Here is an example:
Here you can see an
accountId tag being used to filter workloads to a specific account.
Tags help you to:
- Organize data coming from a large number of sources and/or to a large number of New Relic accounts.
- Identify teams, roles, environments, or regions to know who’s responsible for what (see example use cases).
- Better organize and search dashboards and workloads.
- Query and chart APM data.
Tags are useful for organizing data at a high level. If you want to add more fine-grained detail, like capturing user names or other high-cardinality values, custom attributes or custom events are a better solution.
Tags were previously called
labels in the New Relic UI. You may sometimes see
labelin our code; for example, some of our APM agent config files use a
label config option for tags.
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
- Allowed characters:
- Characters must be UTF-8.
- When using NerdGraph 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
Before adding tags, we recommend first seeing how our default tags work for you. When you're ready to add your own tags, review the following best practices tips to get the most out of them.
- 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: EMEAis better than
Param8323 : 1229072).
- Avoid including several values like
regions: EMEA | US | LATAMin a single tag. We recommend using three different tags for that, like
region: us, and
region: latam. If you want to match multiple tags, you can do that using the advanced options in the filter UI.
- Try to be consistent with tag language across your teams and entities.
- Be consistent with naming. For example, avoid using both
- Be consistent with format. For example, avoid using both
- Although tag searching is not case-sensitive in the UI and API, try to be consistent with capitalization. For example, avoid using both
Tags help 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. Then:
- 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.
Here are some examples of common ways to use tags to organize data:
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:
Use the filter field at the top of the New Relic Explorer to filter down to the entities you care about. You can use multiple filter conditions.
To filter down to certain entities using tags:
- From one.newrelic.com, click Explorer.
- Click the Filter by... field to see a dropdown of available attributes and tags.
- 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 icon.
Select an entity. Near the top of the page, select the icon.
To use the API to view tags, see our NerdGraph docs.
You can query APM tags using NRQL. Minimum agent versions:
- C: not available
- Go: 2.3.0
- Java: 4.9.0
- .NET: 8.17
- Node: v4.13.0
- PHP: not available
- Python: v184.108.40.206
- Ruby: 220.127.116.112
Here are some query examples: