Docker Tag Extraction

Docker Tag Extraction

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.

TagCardinalityRequirement
container_nameHighN/A
container_idHighN/A
rancher_containerHighRancher environment
mesos_taskOrchestratorMesos environment
docker_imageLowN/A
image_nameLowN/A
short_imageLowN/A
image_tagLowN/A
swarm_serviceLowSwarm environment
swarm_namespaceLowSwarm environment
rancher_stackLowRancher environment
rancher_serviceLowRancher environment
envLowUnified service tagging enabled
versionLowUnified service tagging enabled
serviceLowUnified service tagging enabled
marathon_appLowMarathon environment
chronos_jobLowMesos environment
chronos_job_ownerLowMesos environment
nomad_taskLowNomad environment
nomad_jobLowNomad environment
nomad_groupLowNomad environment

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.

Extract labels as tags

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 Docker label <LABEL_NAME> and transform it as a tag key <TAG_KEY> within Datadog, add the following environment variable to the Datadog Agent:

DD_DOCKER_LABELS_AS_TAGS='{"<LABEL_NAME>": "<TAG_KEY>"}'

For example, you could set up:

DD_DOCKER_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_DOCKER_LABELS_AS_TAGS='{"foo": "bar"}', both foo and FOO are mapped to bar.

To extract a given Docker 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:

docker_labels_as_tags:
  <LABEL_NAME>: <TAG_KEY>

For example, you could set up:

docker_labels_as_tags:
  com.docker.compose.service: service_name

Extract environment variables as tags

Datadog automatically collects common tags from Docker, Kubernetes, ECS, Swarm, Mesos, Nomad, and Rancher. To extract even more tags, use the following options:

Environment VariableDescription
DD_DOCKER_LABELS_AS_TAGSExtract docker container labels
DD_DOCKER_ENV_AS_TAGSExtract docker container environment variables
DD_KUBERNETES_POD_LABELS_AS_TAGSExtract pod labels
DD_CHECKS_TAG_CARDINALITYAdd tags to check metrics
DD_DOGSTATSD_TAG_CARDINALITYAdd tags to custom metrics

Starting with Agent v7.20+, a containerized Agent can Autodiscover tags from Docker 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 Docker 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_DOCKER_ENV_AS_TAGS='{"<ENVVAR_NAME>": "<TAG_KEY>"}'

For example, you could set up:

DD_DOCKER_ENV_AS_TAGS='{"ENVIRONMENT":"env"}'

To extract a given Docker 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:

docker_env_as_tags:
  <ENVVAR_NAME>: <TAG_KEY>

For example, you could set up:

docker_env_as_tags:
  ENVIRONMENT: env

Further Reading