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, refer to 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