Getting Started with Tags

Getting Started with Tags


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 data points.

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

Tag Key Allows for
host Correlation between metrics, traces, processes, and logs
device Segregation of metrics, traces, processes, and logs by device or disk
source Span filtering and automated pipeline creation for log management
service Scoping of application specific data across metrics, traces, and logs
env Scoping of application specific data across metrics, traces, and logs
version Scoping of application specific data across metrics, traces, and logs

Why it matters

Typically, it’s helpful to look at containers, VMs, and cloud infrastructure at the service level in aggregate. For example, it’s more helpful to look at CPU usage across a collection of hosts that represents a service, rather than CPU usage for server A or server B separately.

Containers and cloud environments regularly churn through hosts, so it is critical to tag these to allow for aggregation of the metrics you’re getting.

Defining 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
    • Periods
    • Slashes

    Other special characters are converted to underscores.

    Note: A tag cannot end with a colon, for example tag:

  2. Tags can be up to 200 characters long and support Unicode (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. Note: host and device tags are excluded from this conversion.

  4. A tag can be in the format value or <KEY>:<VALUE>. For optimal functionality, Datadog recommends constructing tags in the <KEY>:<VALUE> format. 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 shouldn’t 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.

Assigning tags

Tagging methods

Tags may be assigned using any (or all) of the following methods. See Assigning Tags to learn more:

Method Assign tags
Configuration Files Manually in your main Agent or integration configuration files.
UI In the Datadog site
API When using Datadog’s API
DogStatsD When submitting metrics with DogStatsD

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.

Using tags

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. See Using Tags to learn more:

Area Use Tags to
Events Filter the event stream
Dashboards Filter and group metrics on graphs
Infrastructure Filter and group on the host map, infrastructure list, live containers, and live processes views
Monitors Manage monitors, create monitors, or manage downtime
Metrics Filter and group with the metric explorer
Integrations Optionally limit metrics for AWS, Google Cloud, and Azure
APM Filter Analytics or navigate to other areas with the service map
Notebooks Filter and group metrics on graphs
Logs Filter logs search, analytics, patterns, live tail, and pipelines
SLOs Search for SLOs, grouped metric-based SLOs, grouped monitor-based SLOs
Developers Pull information or setup different areas in the UI with the API
Billing Report on Datadog usage by choosing up to three tags, for example: env, team, and account_id

Further Reading