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.

Applying Tags

Tags must start with a letter, and after that may contain alphanumerics, underscores, minuses, colons, periods and slashes. Other characters will get converted to underscores. Tags can be up to 200 characters long and support unicode. Tags will be converted to lowercase.

For optimal functionality, we recommend constructing tags that use the key:value syntax. Examples of commonly used metric tag keys are env, instance, name, and role. Note that device, host, and source are "reserved" tag keys and cannot be specified in the standard way.

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

  • Agent Tags (datadog.conf)
  • 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")


We store one time series per host + metric + tag combination on our backend, thus we cannot support infinitely bounded tags. Please don't include endlessly growing tags in your metrics, like timestamps or user ids. Please limit each metric to 1000 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.

Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk