Overview

Tags are a way of adding dimensions to Datadog telemetries so they can be filtered, aggregated, and compared in Datadog visualizations. Using tags enables you to observe aggregate performance across several hosts and (optionally) narrow the set further based on specific elements. In summary, tagging is a method to observe aggregate datapoints.

Tags are key:value pairs containing two parts:

• The tag key is the identifier. The tag key is case sensitive.
• The tag value is the specific data or information associated with the key. Tag values are not unique per resource and can be used across many resources in a key:value pair.

Tagging binds different data types in Datadog, allowing for correlation and calls to action between metrics, traces, and logs. This is accomplished with reserved tag keys:

Datadog recommends looking at containers, VMs, and cloud infrastructure at the service level in aggregate. For example, look at CPU usage across a collection of hosts that represents a service, rather than CPU usage for server A or server B separately.

Because containers and cloud environments regularly churn through hosts, using tags is important to aggregate your metrics.

Define tags

Below are Datadog’s tagging requirements:

1. Tags must start with a letter and after that may contain the characters listed below:

   • Alphanumerics
   • Underscores
   • Minuses
   • Colons
   • Commas
   • Periods
   • Slashes

   Other special characters are converted to underscores.

   Notes:

   • A tag that starts with a digit may be accepted in some contexts, such as env tags set at the Agent level. However, tags that don’t follow standard naming rules may not work consistently across all Datadog products and can increase tag cardinality. Start tags with a letter unless a specific product explicitly supports otherwise.
   • The DD_TAGS environment variable uses whitespace as a separator between tags. Whitespace in DD_TAGS values is not converted to underscores. For example, DD_TAGS="test:this is a test" produces four separate tags: test:this, is, a, and test. To set a tag value that contains spaces, use a YAML configuration file or integration annotations, where whitespace is converted to underscores.

2. Tags can be up to 200 characters long and support Unicode letters (which includes most character sets, including languages such as Japanese).

3. Tags are converted to lowercase. Therefore, CamelCase tags are not recommended. Authentication (crawler) based integrations convert camel case tags to underscores, for example TestTag –> test_tag.

4. A tag can be in the format value or <KEY>:<VALUE>. Commonly used tag keys are env, instance, and name. The key always precedes the first colon of the global tag definition, for example:

   Tag	Key	Value
   env:staging:east	env	staging:east
   env_staging:east	env_staging	east

5. Tags should not originate from unbounded sources, such as epoch timestamps, user IDs, or request IDs. Doing so may infinitely increase the number of metrics for your organization and impact your billing.

6. Limitations (such as downcasing) only apply to metric tags, not log attributes or span tags.

Assign tags

Tagging methods

Tags may be assigned using any (or all) of the following methods.

For more information, see Assigning Tags.

Unified service tagging

As a best practice, Datadog recommends using unified service tagging when assigning tags. Unified service tagging ties Datadog telemetry together through the use of three standard tags: env, service, and version. To learn how to configure your environment with unified tagging, see Unified Service Tagging.

Tag inheritance

All metrics, logs, traces, and integrations go through a process of host-tag inheritance as data is ingested into Datadog. Since data is associated with a given hostname, those components inherit all the host-level tags associated with that host. These tags are visible in the infrastructure list for a given host, sourced from either the cloud provider or the Datadog Agent. See missing host-level tags on new hosts or nodes for more information.

Because tags can be inherited from multiple sources, choose unique and specific key names to avoid duplicating them across sources. For example, if you’ve set a service key on a host (service:my-host) and a service key on a pod running on that host (service:my-service), your data inherits both tags. Opt for more differentiated key names (such as infra_service) to avoid duplicate tag keys.

Tag precedence

The Datadog Agent does not enforce a precedence order for tags set from different sources. Instead, the Agent collects all tags from every available source, stores each unique value for a given tag key, and emits all of them with the telemetry.

This means a single tag key can have multiple values if it’s configured differently across sources. For example, if the service tag is set to payments in an environment variable, checkout in the Agent YAML, and orders in a tracing client configuration, telemetry for that service could include:

service:payments
service:checkout
service:orders

Downstream filters or dashboards should explicitly filter on the desired value if you expect only one.

Usage

After you have assigned tags at the host and integration level, start using them to filter and group your metrics, traces, and logs. Tags are used in the following areas of your Datadog platform.

For more information, see Using Tags.

Further Reading

Additional helpful documentation, links, and articles:

Learn how to assign tagsDOCUMENTATION Learn how to configure unified service taggingDOCUMENTATION Learn how to use tagsDOCUMENTATION Join an interactive session on effective tagging with DatadogFOUNDATION ENABLEMENT Design effective executive dashboards with DatadogBLOG