Overview

The Datadog Docker Agent is a version of the Datadog Agent that supports Docker, containerd, and Podman runtimes. For supported Docker versions, see Supported Platforms.

Install the Datadog Docker Agent

Follow the in-app installation flow in Datadog. This is the recommended flow, which helps you create your docker run command with your API key, the required minimum configurations, and toggles for various Datadog features.

Manually run the Datadog Docker Agent

The Fleet Automation flow helps configure your Datadog Agent container with Datadog’s recommended instructions. To configure this manually, see the examples below.

Use the following command to run the Agent as a Docker container once on each host you want to monitor. Replace <DATADOG_API_KEY> with your Datadog API key and <DATADOG_SITE> with your .

docker run -d --cgroupns host --pid host --name dd-agent \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /proc/:/host/proc/:ro \
  -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
  -e DD_SITE=<DATADOG_SITE> \
  -e DD_API_KEY=<DATADOG_API_KEY> \
  registry.datadoghq.com/agent:7

docker run -d --name dd-agent `
  -v \\.\pipe\docker_engine:\\.\pipe\docker_engine `
  -e DD_SITE=<DATADOG_SITE> `
  -e DD_API_KEY=<DATADOG_API_KEY> `
  registry.datadoghq.com/agent:7

Note: For Docker Compose, see Compose and the Datadog Agent. For deploying the Agent in Podman, see the instructions in Using the Docker integration with Podman container runtime.

Integrations

After the Datadog Docker Agent is up and running, you can configure Datadog integrations to collect metrics and logs automatically from your application containers. Datadog’s Container Autodiscovery enables you to define monitoring configuration for dynamic resources in containerized systems.

Configuration options for the Datadog Docker Agent

Container registries

Images are available for 64-bit x86 and Arm v8 architectures. Datadog publishes container images to the Datadog Container Registry, Google Artifact Registry (GAR), Amazon ECR, Azure ACR, and Docker Hub:

By default, the above instructions pull the image from the Datadog Container Registry (registry.datadoghq.com). If you use this registry, ensure your firewall allows traffic to us-docker.pkg.dev/datadog-prod/public-images, as the registry may redirect requests to this URL.

Environment variables

In a non-containerized environment, configuration options for the Datadog Agent are set in datadog.yaml. For the Datadog Docker Agent, you can set datadog.yaml configuration options through environment variables.

Global options

DD_API_KEY

Your Datadog API key (required).

DD_ENV

Sets the global env tag for all data emitted.

DD_HOSTNAME

Hostname to use for metrics (if autodetection fails).

DD_HOSTNAME_FILE

In some environments, auto-detection of the hostname is not adequate, and you cannot set the value with environment variables. In these cases, you can use a file on the host to provide an appropriate value. If DD_HOSTNAME is set to a non-empty value, this option is ignored.

DD_TAGS

Host tags separated by spaces. For example: key1:value1 key2:value2.

DD_SITE

Destination site for your metrics, traces, and logs. Set your Datadog site to: . Defaults to datadoghq.com.

DD_DD_URL

Optional setting to override the URL for metric submission.

DD_URL (6.36+/7.36+)

Alias for DD_DD_URL. Ignored if DD_DD_URL is already set.

DD_CHECK_RUNNERS

The Agent runs all checks concurrently by default (default value = 4 runners). To run the checks sequentially, set the value to 1. If you need to run a high number of checks (or slow checks), the collector-queue component may fall behind and fail the health check. You can increase the number of runners to run checks in parallel.

DD_APM_ENABLED

Enables trace collection. Defaults to true. For more information about additional trace collection environment variables, see Tracing Docker Applications.

DD_LOGS_CONFIG_EXPECTED_TAGS_DURATION

In some environments, the initial logs from hosts might not include the correct tags. If you’re missing tags on new hosts in your logs, include this environment variable and set it to "10m".

Proxy settings

Starting with Agent v6.4.0 (and v6.5.0 for the Trace Agent), you can override the Agent proxy settings with the following environment variables:

DD_PROXY_HTTP

An HTTP URL to use as a proxy for http requests.

DD_PROXY_HTTPS

An HTTPS URL to use as a proxy for https requests.

DD_PROXY_NO_PROXY

A space-separated list of URLs for which no proxy should be used.

For more information about proxy settings, see the Agent v6 Proxy documentation.

Optional collection Agents

Optional collection Agents are disabled by default for security or performance reasons. Use these environment variables to enable them:

DD_APM_NON_LOCAL_TRAFFIC

Allow non-local traffic when tracing from other containers.

DD_LOGS_ENABLED

Enable log collection with the Logs Agent.

DD_PROCESS_CONFIG_PROCESS_COLLECTION_ENABLED

Enable live process collection with the Process Agent. The live container view is already enabled by default if the Docker socket is available.

DogStatsD (custom metrics)

Send custom metrics with the StatsD protocol:

DD_DOGSTATSD_NON_LOCAL_TRAFFIC

Listen to DogStatsD packets from other containers (required to send custom metrics).

DD_HISTOGRAM_PERCENTILES

The histogram percentiles to compute (separated by spaces). The default is 0.95.

DD_HISTOGRAM_AGGREGATES

The histogram aggregates to compute (separated by spaces). The default is "max median avg count".

DD_DOGSTATSD_SOCKET

Path to the unix socket to listen to. Must be in a rw mounted volume.

DD_DOGSTATSD_ORIGIN_DETECTION

Enable container detection and tagging for UNIX socket metrics.

DD_DOGSTATSD_TAGS

Additional tags to append to all metrics, events, and service checks received by this DogStatsD server. For example: "env:golden group:retrievers".

DD_USE_DOGSTATSD

Enable or disable sending custom metrics from the DogStatsD library. Learn more about DogStatsD over Unix Domain Sockets.

Tagging

As a best practice, Datadog recommends using unified service tagging when assigning tags.

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

DD_CONTAINER_LABELS_AS_TAGS

Extract container labels. This env is equivalent to DD_DOCKER_LABELS_AS_TAGS.

DD_CONTAINER_ENV_AS_TAGS

Extract container environment variables. This env is equivalent to DD_DOCKER_ENV_AS_TAGS.

DD_COLLECT_EC2_TAGS

Extract custom EC2 tags without using the AWS integration.

See the Docker Tag Extraction documentation to learn more.

Using secret files

Integration credentials can be stored in Docker or Kubernetes secrets and used in Autodiscovery templates. For more information, see the Secrets Management documentation.

Ignore containers

Exclude containers from logs collection, metrics collection, and Autodiscovery. Datadog excludes Kubernetes and OpenShift pause containers by default. These allowlists and blocklists apply to Autodiscovery only; traces and DogStatsD are not affected. The value for these environment variables support regular expressions.

DD_CONTAINER_INCLUDE

Allowlist of containers to include (separated by spaces). Use .* to include all. For example: "image:image_name_1 image:image_name_2", image:.* When using ImageStreams inside OpenShift environments, use the container name instead of image. For example: "name:container_name_1 name:container_name_2", name:.*

DD_CONTAINER_EXCLUDE

Blocklist of containers to exclude (separated by spaces). Use .* to exclude all. For example: "image:image_name_3 image:image_name_4", image:.* (Note: This variable is only honored for Autodiscovery.)

DD_CONTAINER_INCLUDE_METRICS

Allowlist of containers whose metrics you wish to include.

DD_CONTAINER_EXCLUDE_METRICS

Blocklist of containers whose metrics you wish to exclude.

DD_CONTAINER_INCLUDE_LOGS

Allowlist of containers whose logs you wish to include.

DD_CONTAINER_EXCLUDE_LOGS

Blocklist of containers whose logs you wish to exclude.

DD_AC_INCLUDE

Deprecated. Allowlist of containers to include (separated by spaces). Use .* to include all. For example: "image:image_name_1 image:image_name_2", image:.*

DD_AC_EXCLUDE

Deprecated. Blocklist of containers to exclude (separated by spaces). Use .* to exclude all. For example: "image:image_name_3 image:image_name_4", image:.* (Note: This variable is only honored for Autodiscovery.)

Additional examples are available on the Container Discovery Management page.

Note: The kubernetes.containers.running, kubernetes.pods.running, docker.containers.running, .stopped, .running.total and .stopped.total metrics are not affected by these settings. All containers are counted. This does not affect your per-container billing.

Note: When using containerd, it’s possible to ignore containers by namespace using DD_CONTAINERD_NAMESPACES and DD_CONTAINERD_EXCLUDE_NAMESPACES. Both are a space-separated list of namespaces. When DD_CONTAINERD_NAMESPACES is set, the agent reports data for the containers that belong to a namespace present in the list. When DD_CONTAINERD_EXCLUDE_NAMESPACES is set, the agent reports data for all the containers except the ones that belong to a namespace of the list.

Autodiscovery

DD_LISTENERS

Autodiscovery listeners to run.

DD_EXTRA_LISTENERS

Additional Autodiscovery listeners to run. They are added in addition to the variables defined in the listeners section of the datadog.yaml configuration file.

DD_CONFIG_PROVIDERS

The providers the Agent should call to collect checks configurations. The default provider is docker. The Docker provider handles templates embedded in container labels.

DD_EXTRA_CONFIG_PROVIDERS

Additional Autodiscovery configuration providers to use. They are added in addition to the variables defined in the config_providers section of the datadog.yaml configuration file.

Miscellaneous

DD_PROCESS_AGENT_CONTAINER_SOURCE

Overrides container source auto-detection to force a single source. e.g "docker", "ecs_fargate", "kubelet". This is no longer needed since Agent v7.35.0.

DD_HEALTH_PORT

Set this to 5555 to expose the Agent health check at port 5555.

Commands

See the Agent Commands guides to discover all the Docker Agent commands.

Data collected

Metrics

By default, the Docker Agent collects metrics with the following core checks. To collect metrics from other technologies, see the Integrations section.

Events

The Docker Agent sends events to Datadog when an Agent is started or restarted.

Service checks

datadog.agent.up
Returns CRITICAL if the Agent is unable to connect to Datadog, otherwise returns OK.

datadog.agent.check_status
Returns CRITICAL if an Agent check is unable to send metrics to Datadog, otherwise returns OK.

Uninstall Single Step APM Instrumentation

If you installed the Datadog Docker Agent with Single Step APM Instrumentation, and you want to uninstall the Agent, you need to run additional commands to uninstall APM Instrumentation.

Further Reading

Additional helpful documentation, links, and articles:

Check out the latest Datadog Containers releases! (App login required).RELEASE NOTES Collect your application logsDOCUMENTATION Collect your application tracesDOCUMENTATION Collect your Prometheus metricsDOCUMENTATION Automatically collect your application's metrics and logsDOCUMENTATION Limit data collection to a subset of containers onlyDOCUMENTATION Assign tags to all data emitted by a containerDOCUMENTATION