Tags are key-value pairs, for example 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 such as 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:
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 some examples.
Better organize and search dashboards and workloads.
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.
Manage tags
Some important attributes are available by default to be used as tags. For example, the account name, the account ID, and some basic host and server metadata. You can't remove these available-by-default tags.
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.
Add tags
Go to one.newrelic.com and select a monitored entity, like a monitored app or host.
Near the entity's name at the top of the page, select the See metadata and manage tags menu.
In the Add a new tag... field of the pop-up menu, add a tag with this format: accountId: 123456789.
For APM agents, if you want to use those tags in NRQL queries, restart your service.
Remove tags
Go to one.newrelic.com and select a monitored entity, like a monitored app or host.
Near the entity's name at the top of the page, select the See metadata and manage tags menu.
In the menu that pops up, click the Remove tags toggle.
Click the next to the tag you want to remove.
For APM agents, if you want to use those tags in NRQL queries, restart your service.
Navigate to a condition.
Near the condition's name at the top of the form, click Manage tags.
Click the Filter by ... field to see a dropdown of available attributes and tags or enter a tag you want to filter by, such as accountId: 123456789.
Best practices
Follow these best practices to get the most out of your 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 `key-name`.
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.
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.
Although tag searching is not case-sensitive in the UI and API, try to be consistent with capitalization. For example, avoid using both env: staging and env: Staging.
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.
Tag examples
Here are some examples of common ways to use tags to organize data.
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 tags
team: backend
team: frontend
team: db
### Role tags
roles: architecture
roles: devops
roles: pm
### Region tags
region: emea
region: america
region: asia
You can create entities for the environment they belong to. For example:
env: production
env: qa
env: development
env: staging
You can create tags related to criticality levels, which lets you easier track the most critical issues. For example:
layer: level1
layer: level2
layer: level3
Custom queries, dashboards, and alerts
Different features handle tags differently. Here are some details about how you can use NRQL to query tag data, or create NRQL condition alerts.
You can query APM tags using NRQL. These are the supported APM agents:
Go v2.3.0 or higher
Java v4.9.0 or higher
.NET v8.17 or higher
Node v4.13.0 or higher
PHP v10.0.0.312 or higher
Python v4.10.0.112 or higher
Ruby v6.1.0.352 or higher
Query examples
Given a service that is distributed across nine shards, each shard assigned as an environment, we can plot the transaction throughput on all shards using a wildcard query like:
FROM Metric WHERE appName LIKE'MyApp (%'AND transactionType ='Other'
FACET tags.Environment TIMESERIES
To see the number of transactions per service for a specific team, we might use a query like:
FROMTransactionSELECTcount(*)
WHERE tags.Team ='team-a'
FACET tags.Project TIMESERIES
You can use a query for your services’ error rate for setting an alert without having to create a rule for each service. Here is the error rate for all services on a team called team-b. And this alert will automatically monitor any new app names added with the team tag.
FROM Metric SELECTcount(apm.service.error.count)/count(apm.service.transaction.duration)
WHERE tags.Team ='team-b' FACET appName
Related to this, you might create a general rule for a specific service deployed across several environments, so that we have an alarm for a single service monitoring each environment individually:
From Metric SELECTcount(apm.service.error.count)/count(apm.service.transaction.duration)
WHERE tags.Project ='MyProject' FACET tags.Environment
Query and alert on attributes
Some important attributes are used as tags. You can query all attributes and create custom charts using NRQL, and create NRQL alert conditions.