Docker Agent

Overview

The Datadog Docker Agent is the containerized version of the host Agent. The official Docker image is available on Docker Hub.

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

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.

Dropdown

DOCKER_CONTENT_TRUST=1 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> datadog/agent:7

DOCKER_CONTENT_TRUST=1 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> 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 datadog/agent:latest

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

DOCKER_CONTENT_TRUST=1 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> 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_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. Valid options are `datadoghq.com` for the Datadog US site, and `datadoghq.eu` for the Datadog EU site.
`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 with the Trace Agent.
`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"]`.

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.

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:.`
`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 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.