Docker Agent

Docker Agent

Overview

The Datadog Docker Agent is the containerized version of the host Agent. The official Docker image is available on Docker Hub, GCR, and ECR-Public.

Images are available for 64-bit x86 and Arm v8 architectures.

Docker Hub GCR ECR-Public
Agent v6+
docker pull datadog/agent
Agent v6+
docker pull gcr.io/datadoghq/agent
Agent v6+
docker pull public.ecr.aws/datadog/agent
Agent v5
docker pull datadog/docker-dd-agent
Agent v5
docker pull gcr.io/datadoghq/docker-dd-agent
Agent v5
docker pull public.ecr.aws/datadog/docker-dd-agent

Setup

If you haven’t installed the Docker Agent, follow the in-app installation instructions or see below. For supported versions, see the Agent documentation. Use the one-step install command. Replace <YOUR_DATADOG_API_KEY> with your Datadog API key.

docker run -d --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_API_KEY=<DATADOG_API_KEY> gcr.io/datadoghq/agent:7

For ECR-public:

docker run -d --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_API_KEY=<DATADOG_API_KEY> public.ecr.aws/datadog/agent:7

Note: If you’re using a different registry besides GCR or ECR-public, make sure to update the image.

For Amazon Linux < v2:

docker run -d --name dd-agent -v /var/run/docker.sock:/var/run/docker.sock:ro -v /proc/:/host/proc/:ro -v /cgroup/:/host/sys/fs/cgroup:ro -e DD_API_KEY=<DATADOG_API_KEY> gcr.io/datadoghq/agent:7

For ECR-public:

docker run -d --name dd-agent -v /var/run/docker.sock:/var/run/docker.sock:ro -v /proc/:/host/proc/:ro -v /cgroup/:/host/sys/fs/cgroup:ro -e DD_API_KEY=<DATADOG_API_KEY> public.ecr.aws/datadog/agent:7

For Amazon Linux v2:

docker run -d --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_API_KEY=<DATADOG_API_KEY> gcr.io/datadoghq/agent:7

For ECR-public:

docker run -d --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_API_KEY=<DATADOG_API_KEY> public.ecr.aws/datadog/agent:7

The Datadog Agent is supported in Windows Server 2019 (LTSC) and version 1909 (SAC).

docker run -d --name dd-agent -e DD_API_KEY=<API_KEY> -v \\.\pipe\docker_engine:\\.\pipe\docker_engine gcr.io/datadoghq/agent

For ECR-Public:

docker run -d --name dd-agent -e DD_API_KEY=<API_KEY> -v \\.\pipe\docker_engine:\\.\pipe\docker_engine public.ecr.aws/datadog/agent

(Optional) To run an unprivileged installation, add --group-add=<DOCKER_GROUP_ID> to the install command, for example:

docker run -d --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_API_KEY=<DATADOG_API_KEY> gcr.io/datadoghq/agent:7 --group-add=<DOCKER_GROUP_ID>

For ECR-Public:

docker run -d --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_API_KEY=<DATADOG_API_KEY> public.ecr.aws/datadog/agent:7 --group-add=<DOCKER_GROUP_ID>

Note: For Docker Compose, see Compose and the Datadog Agent.

Integrations

Once the Agent is up and running, use Datadog’s Autodiscovery feature to collect metrics and logs automatically from your application containers.

Environment variables

The Agent’s main configuration file is datadog.yaml. For the Docker Agent, datadog.yaml configuration options are passed in with environment variables.

Global options

Env Variable Description
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: simple-tag-0 tag-key-1:tag-value-1
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_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 might fall behind and fail the healthcheck. You can increase the number of runners to run checks in parallel.

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:

Env Variable Description
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:

Env Variable Description
DD_APM_ENABLED Enable trace collection. Read about additional trace collection environment variables in Tracing Docker Applications.
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_AGENT_ENABLED Enable live process collection with the Process Agent. The live container view is already enabled by default if the Docker socket is available. If set to false, the live process collection and the live container view are disabled.

DogStatsD (custom metrics)

Send custom metrics with the StatsD protocol:

Env Variable Description
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_DOGSTATSD_DISABLE Disables 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:

Env Variable Description
DD_DOCKER_LABELS_AS_TAGS Extract Docker container labels
DD_DOCKER_ENV_AS_TAGS Extract Docker container environment variables
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.

Env Variable Description
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" (Note: This variable is only honored for Autodiscovery.), image:.*
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" (Note: This variable is only honored for Autodiscovery.), image:.*

Additional examples are available on the Container Discover 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.

Misc

Env Variable Description
DD_PROCESS_AGENT_CONTAINER_SOURCE Overrides container source auto-detection to force a single source. e.g "docker", "ecs_fargate", "kubelet"
DD_HEALTH_PORT Set this to 5555 to expose the Agent health check at port 5555.

You can add extra listeners and config providers using the DD_EXTRA_LISTENERS and DD_EXTRA_CONFIG_PROVIDERS environment variables. They are added in addition to the variables defined in the listeners and config_providers section of the datadog.yaml configuration file.

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.

Check Metrics
CPU System
Disk Disk
Docker Docker
File Handle System
IO System
Load System
Memory System
Network Network
NTP NTP
Uptime System

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.

Further Reading