The Service Map for APM is here!

Getting started with tags


Tags are a way of adding dimensions to metrics, so they can be sliced, diced, aggregated, and compared on the front end. Using tags enables you to observe aggregate performance across a number of hosts and (optionally) narrow the set further based on specific elements. In a nutshell, tagging is a method to scope aggregated data.

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 across a collection of hosts that represents a service, rather than CPU 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.

Tags best practices

A few best practices on tags:

  1. Tags must start with a letter, and after that may contain:

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

    Other special characters get converted to underscores. Note: A tag cannot end with a colon (e.g., tag:)

  2. Tags can be up to 200 characters long and support unicode.

  3. Tags are converted to lowercase.

  4. A tag can have a value or a key:value syntax: For optimal functionality, we recommend constructing tags that use the key:value syntax. The key is always what precedes the first colon of the global tag definition, e.g.:

    • role:database:mysql is parsed as key:role , value:database:mysql
    • role_database:mysql is parsed as key:role_database , value:mysql

    Examples of commonly used metric tag keys are env, instance, name, and role.

  5. device, host, and source are reserved tag keys and cannot be specified in the standard way.

  6. Tags shouldn’t originate from unbounded sources, such as EPOCH timestamps or user IDs. These tags may impact platform performance and billing.

Applying Tags

Tags may be added using any (or all) of the following methods:

  • Agent Tags (datadog.yaml)
  • DogStatsD Tags
  • Integration/Check Tags (each check on the local host supports tags by editing the yaml)
  • Tags generated by other services such as AWS, Azure, GCE, etc.
  • Tags in the API - note other endpoints support tags as well such as Events and Metrics
  • Chef Roles and Puppet Tags (Chef and Puppet use the API - this may obviously be extended to other configuration management tools by you or Datadog)
  • Manually adding tags using the Infrastructure List (hover over host->select “Inspect”->“Edit Tags”)


Here is an example of tags using the time-series chart editor. For the first screenshot, no tags have been applied, and we’re observing average CPU across all hosts:


In this next example, we’ve applied a tag (region:eastus) that enables us to look at CPU across the US East Region. We’ve used region as an example, but you could use any arbitrary tag, including application, service, environment, etc.


In this last example, we’ve used the second empty field labeled as “everything” by option to show an individual timeseries line for each host. Now we’re seeing server CPU for individual hosts running in the US East Region.


We can also add additional tags to narrow down our scope even further - for example, hosts in region:eastus and env:production. Tags are extremely powerful, and they are ubiquitous in Datadog. They can be applied to all core elements, including alerts and host maps.

Further Reading