Overview
The Datadog Agent can create and assign tags to all metrics, traces, and logs emitted by a container based on its labels or environment variables.
If you are running the Agent as a binary on a host, configure your tag extractions with the Agent tab instructions. If you are running the Agent as a container, configure your tag extraction with the Containerized Agent tab instructions.
Out-of-the-box tagging
The Agent can autodiscover and attach tags to all data emitted by containers. The list of tags attached depends on the Agent cardinality configuration. Tag Cardinality can impact billing as different cardinality settings impact the number of emitted metrics.
| Tag | Cardinality | Requirement |
|---|
container_name | High | N/A
Note: not included for the containerd runtime. |
container_id | High | N/A |
rancher_container | High | Rancher environment |
mesos_task | Orchestrator | Mesos environment |
docker_image | Low | N/A
Note: not included for the containerd runtime. |
image_name | Low | N/A |
short_image | Low | N/A |
image_tag | Low | N/A |
swarm_service | Low | Swarm environment |
swarm_namespace | Low | Swarm environment |
rancher_stack | Low | Rancher environment |
rancher_service | Low | Rancher environment |
env | Low | Unified service tagging enabled |
version | Low | Unified service tagging enabled |
service | Low | Unified service tagging enabled |
marathon_app | Low | Marathon environment |
chronos_job | Low | Mesos environment |
chronos_job_owner | Low | Mesos environment |
nomad_task | Low | Nomad environment |
nomad_job | Low | Nomad environment |
nomad_group | Low | Nomad environment |
git.commit.sha | Low | org.opencontainers.image.revision used |
git.repository_url | Low | org.opencontainers.image.source used |
Unified service tagging
As a best practice in containerized environments, 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 the dedicated unified service tagging documentation.
Starting with Agent v6.0+, the Agent can collect labels for a given container and use them as tags to attach to all data emitted by this container.
To extract a given container label <LABEL_NAME> and transform it as a tag key <TAG_KEY> within Datadog, add the following environment variable to the Datadog Agent:
DD_CONTAINER_LABELS_AS_TAGS='{"<LABEL_NAME>":"<TAG_KEY>"}'
For example, you could set up:
DD_CONTAINER_LABELS_AS_TAGS='{"com.docker.compose.service":"service_name"}'
Note: <LABEL_NAME> is not case-sensitive. For example, if you have labels named foo and FOO, and you set DD_CONTAINER_LABELS_AS_TAGS='{"foo": "bar"}', both foo and FOO are mapped to bar.
Note: DD_CONTAINER_LABELS_AS_TAGS is equivalent to the old DD_DOCKER_LABELS_AS_TAGS, and DD_CONTAINER_ENV_AS_TAGS to DD_DOCKER_ENV_AS_TAGS.
To extract a given container label <LABEL_NAME> and transform it as a tag key <TAG_KEY> within Datadog, add the following configuration block in the Agent datadog.yaml configuration file:
container_labels_as_tags:
<LABEL_NAME>: <TAG_KEY>
For example, you could set up:
container_labels_as_tags:
com.docker.compose.service: service_name
Datadog automatically collects common tags from Docker, Kubernetes, ECS, Swarm, Mesos, Nomad, and Rancher. To extract even more tags, use the following options:
| Environment Variable | Description |
|---|
DD_CONTAINER_LABELS_AS_TAGS | Extract container labels |
DD_CONTAINER_ENV_AS_TAGS | Extract container environment variables |
DD_KUBERNETES_POD_LABELS_AS_TAGS | Extract pod labels |
DD_CHECKS_TAG_CARDINALITY | Add tags to check metrics |
DD_DOGSTATSD_TAG_CARDINALITY | Add tags to custom metrics |
Starting with Agent v7.20+, a containerized Agent can Autodiscover tags from container labels. This process allows the Agent to associate custom tags to all data emitted by a container without modifying the Agent datadog.yaml file.
Tags should be added using the following format:
com.datadoghq.ad.tags: '["<TAG_KEY_1>:<TAG_VALUE_1>", "<TAG_KEY_2>:<TAG_VALUE_2>"]'
With Agent v6.0+, the Agent can collect environment variables for a given container and use them as tags to attach to all data emitted by this container.
To extract a given container environment variable <ENVVAR_NAME> and transform it as a tag key <TAG_KEY> within Datadog, add the following environment variable to the Datadog Agent:
DD_CONTAINER_ENV_AS_TAGS='{"<ENVVAR_NAME>": "<TAG_KEY>"}'
For example, you could set up:
DD_CONTAINER_ENV_AS_TAGS='{"ENVIRONMENT":"env"}'
To extract a given container environment variable <ENVVAR_NAME> and transform it as a tag key <TAG_KEY> within Datadog, add the following configuration block in the Agent datadog.yaml configuration file:
container_env_as_tags:
<ENVVAR_NAME>: <TAG_KEY>
For example, you could set up:
container_env_as_tags:
ENVIRONMENT: env
Further Reading
Additional helpful documentation, links, and articles:
