Tag
A marker you attach to monitored objects so you can later call up everything with the same property at once. In Datadog the basic form is <code>key:value</code>.
Overview
A tag is a mechanism for putting a common marker on disparate objects such as hosts, containers, metrics, logs, and traces, so that everything sharing an attribute can be called up across them. Datadog also accepts value-only tags, but the <code>key:value</code> form, which makes meanings such as environment or role explicit, is recommended. It looks like a tool for writing search conditions, but in reality it is a design object that decides the unit by which you aggregate, the unit by which you split alerts, and the unit by which you count cost. Because naming conventions are hard to change later, it pays to decide them early in adoption.
A tag is a unit of aggregation, not a search condition
A tag takes the form key:value or a plain value-only string. The part up to the first colon is treated as the key, so for env:staging:east the key is env and the value is staging:east. Datadog recommends key:value over the value-only form because a key lets you write operations such as "split by environment" or "sum by role" mechanically.
- The axis along which graphs are split on dashboards
- The granularity of whether a monitor is split per target or rolled into one notification
- Whether logs, metrics, and traces can be cross-checked with the same conditions
- How many series are created, that is, the amount counted as usage
The last point is easy to overlook. A tag looks the same on screen whether you add or remove it, but as the number of distinct values grows, the number of series held internally grows. It fits reality better to think of tag design not as a matter of presentation but as a matter of deciding the unit of aggregation.
Reserved keys, and the three tags that connect three products
Datadog has keys whose meaning is decided in advance. As of August 2026, the official documentation lists host, device, source, service, env, version, and team as reserved keys. If you repurpose these with a different meaning for your own convenience, the linkage the products expect stops working. Among them, the three keys env, service, and version are called unified service tagging and are positioned as the axis that connects metrics, traces, and logs with the same vocabulary. Whether, during an incident investigation, you can query "only this version, of this service, in production" against all three kinds of data with the same conditions is decided by whether you aligned these three from the start. If you try to align them later, the data ingested in the past carries no marker, so the periods you most want to compare are exactly where the gaps appear.
Pitfalls of character sets and normalization
Tags have mechanical rules, and the string you intended does not necessarily survive intact. Under the rules as of August 2026, a tag must start with a letter, and from the second character onward the allowed characters are letters, digits, underscores, minus signs, colons, periods, and at signs. Slashes are also allowed, but only in tags on logs ingested over HTTP. Any other character, such as a comma, a space, or an emoji, is replaced with an underscore, consecutive underscores are collapsed into one, and leading and trailing underscores are removed. The maximum length is 200 characters including the key, the colon, and the value. Case handling differs by object. Metric tags and span tags are normalized to lowercase, so there is no point writing keys in camel case. Log attributes and span attributes, on the other hand, are case-sensitive and are not normalized. If you treat these as the same, you end up in a state where one side treats two things as identical and the other side treats them as different. Tags ingested from cloud providers also have normalization quirks that differ by provider. The official documentation places side by side the example of AWS turning TestTag into testtag and Alibaba Cloud turning it into test_tag. The environment variable DD_TAGS has a further quirk: spaces are not turned into underscores but are interpreted as separators, so writing test:this is a test produces four tags.
Do not put in values that grow without limit
The design decision with the most impact is to confirm, before adding a tag, whether its set of values is finite. The official documentation warns that using unbounded values such as epoch timestamps, user IDs, or request IDs as tags causes metrics to grow without limit. Tags starting with a digit work in some contexts, but they push toward increasing the number of distinct values and behave inconsistently. What makes this kind of failure troublesome is that it breaks quietly. Graphs still render, searches still work, and only the number of series keeps growing. What tips you off is not a display defect but aggregation getting heavier or usage estimates failing to add up. One more point: the Agent does not enforce a precedence among tags. If you supply the same key from a configuration file, an environment variable, and another route, you can end up with multiple values lined up under a single key. The official documentation itself gives an example of service carrying three values. Because this unintentionally splits the denominator of an aggregation, it is safer to narrow the routes that supply the same key down to one.
When to care about this concept, and common misconceptions
The moment to design tags seriously is when your monitored targets grow to a second one. With one, the name suffices, but from the second onward you need both "view them together" and "view only one", and what supports that switching is tags. Conversely, if you introduce a convention after the targets have multiplied, you hit the wall of being unable to re-mark old data. There are three common misconceptions. First, the assumption that Datadog will absorb inconsistencies in notation. Because normalization is handled differently for metrics and logs, inconsistencies remain where they remain. Second, the assumption that lining up value-only tags without keys is just as good. Value-only tags can be searched, but they cannot serve as an aggregation axis, which bites later. Third, the assumption that more tags are always more convenient. The only axes you can add are those with a finite set of values; values that grow without limit make monitoring itself heavier. The primary source for the tag rules is Datadog's official documentation, Getting Started with Tags. Because most real tags are attached through the Datadog Agent configuration or cloud integrations, the practical side of attaching them starts from those explanations.