Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 37 ยท Metrics and Tags

Datadog Tags: Rules, Unified Service Tagging and Cardinality

Learn Datadog tag syntax and rules, host versus metric tags, unified service tagging with env, service and version, tag policies, and how high cardinality drives cost.

Tags are the most important idea in Datadog. A tag is a label attached to data, written key:value, such as env:prod or service:checkout. Without tags a metric is one global number; with tags you can slice it by host, service, region and version, and you can connect metrics to logs and traces. Good tagging makes Datadog feel like magic; bad tagging makes it slow, confusing and expensive.

Tag syntax and rules

A tag is a string. Datadog treats the part before the first colon as the key and the rest as the value; a tag without a colon is just a key-less "simple tag".

  • Tags must start with a letter, and may contain letters, numbers, underscores, minus signs, colons, periods and slashes. Other characters are converted to underscores.
  • Tags are lowercased: Env:Prod becomes env:prod.
  • A tag can be up to 200 characters long.
  • A trailing underscore is removed, and consecutive special characters collapse.
  • Prefer the key:value form: only key-value tags can be used with by {key} grouping.
  • A key can appear several times on one host or metric with different values (role:web, role:cache).
TEXT
env:prod
service:checkout
team:payments
region:eu-west-1
version:2026.11.3

Where tags come from

  1. Host tags in datadog.yaml or DD_TAGS: applied to everything from that host.
  2. Integration tags in conf.d: applied to that check's metrics.
  3. Automatic tags from the platform: host, cloud tags (region, availability-zone, instance tags), container and Kubernetes tags.
  4. Metric tags added in code (DogStatsD, AgentCheck) or in a log pipeline.
  5. Tag rules in the UI: the Datadog UI lets you attach tags to a host manually, but code-based tags survive rebuilds.

A metric's tag set is the union of those sources.

Unified service tagging

Three reserved tags tie everything together:

Tag Meaning Example
env Deployment environment prod, staging
service The application or component that emits the data checkout
version The code version 2026.11.3

When all three are set the same way on metrics, logs and traces, you can click from a latency graph to logs and traces for that service in that environment and, with version, compare a new deploy against the old one. The setup differs by platform:

  • Host: set DD_ENV, DD_SERVICE, DD_VERSION for your application process (tracing libraries read them).
  • Containers: labels com.datadoghq.tags.env, .service, .version.
  • Kubernetes: labels tags.datadoghq.com/env|service|version on the Deployment and pod template (see containers and Kubernetes).
  • Serverless: environment variables on the function.

Never use different spellings (prod vs production, checkout vs checkout-service) for the same thing: Datadog sees different values.

Choosing good tag keys

Good keys group things you will filter on: env, service, team, region, cluster, tier, customer_tier, version. They have a small, bounded set of values. A short tagging standard document, with allowed keys and values, is worth writing before the third team starts using Datadog. Metrics without Limits lets you control which tag keys are kept queryable per metric, which is how you cut cardinality cost without changing code.

Cardinality: the hidden cost

The number of distinct values of a tag is its cardinality. Each unique combination of tag values on a metric makes a separate time series, and custom metrics are billed by the number of series. Tags with unbounded values explode this:

  • user_id with 1,000,000 users on a metric means up to 1,000,000 series.
  • pod_name changes on every restart, so a deployment that rolls ten times a day creates ten generations of series.
  • request_id creates a new series per request.

The series count for a metric is roughly the product of tag value counts that actually occur together. A metric with env (3 values) x service (40) x region (5) x status_code (8) has up to 4,800 series, which is fine. Adding pod_name (2,000 values) pushes it near ten million.

Rules of thumb:

  1. Keep per-metric tag values bounded and meaningful.
  2. Put unbounded identifiers in logs or traces, not metric tags.
  3. Aggregate away tags you never graph (Metrics without Limits).
  4. Review the Metrics Summary estimated cardinality and the usage page regularly.
Python Stand-in: normalize and validate a tag

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: estimate series count (cardinality)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The product in the stand-in is an upper bound: real series exist only for combinations that actually occur, but a bound shows how quickly the numbers grow.

Using tags in queries and monitors

Filter with braces: {env:prod,service:checkout} (comma means AND), exclude with ! ({env:prod,!service:batch}), and group with by {region}. Use wildcards for values (host:web-*). Monitors then use the same scope, so adding a team tag lets one monitor alert per team. See the query language.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which three tags make up unified service tagging?

    env, service and version are the reserved set that ties metrics, logs and traces together.
  2. 2. What happens to the tag Env:Prod?

    Datadog lowercases tags.
  3. 3. Which tag is the worst choice on a metric used by a million users?

    user_id has unbounded cardinality and would create a series per user.
  4. 4. Why is key:value form preferred over a bare word?

    Grouping needs a key, so env:prod can be grouped by env, while a bare prod cannot.

Summary

  • A tag is a lowercase key:value label; tags start with a letter and are at most 200 characters.
  • Tags come from hosts, integrations, the platform, your code and pipelines.
  • Set env, service and version identically everywhere for unified service tagging.
  • Cardinality (distinct tag-value combinations) drives custom metrics cost; keep tags bounded.

Next: DogStatsD and Custom Metrics