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, see below or the in-app installation instructions. See the Agent documentation for supported versions.

Installation

Use the one-step install command. Replace <YOUR_DATADOG_API_KEY> with your Datadog API key.

DOCKER_CONTENT_TRUST=1 \
docker run -d -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:latest

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:latest

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

Configuration

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

Environment variables

Global options

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:

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:

DogStatsD (custom metrics)

Send custom metrics with the StatsD protocol:

Learn more about DogStatsD over Unix Domain Sockets.

Tagging

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

The map key is the source (label/envvar) name, and the map value is the Datadog tag name, for example:

DD_KUBERNETES_POD_LABELS_AS_TAGS='{"app":"kube_app","release":"helm_release"}'
DD_DOCKER_LABELS_AS_TAGS='{"com.docker.compose.service":"service_name"}'

Additional examples are available on the Tag Assignment and Extraction page.

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.

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

Note: If you are using the containerd runtime, set DD_PROCESS_AGENT_CONTAINER_SOURCE="kubelet" in order to see your containers on the containers page.

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.

Validation

Run the Docker Agent’s status command to verify installation.

Commands

These commands are run on the host.

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.

Integrations

The Docker integration sends metrics automatically with the Docker Agent. To configure other integrations, use Autodiscovery or mounting.

Autodiscovery

Autodiscovery is enabled for the Docker Agent when using the one-step install by mounting /var/run/docker.sock.

To add integrations using Autodiscovery, see the Autodiscovery Integration Templates page.

Mounting conf.d

Your integration configuration files can be copied to /etc/datadog-agent/conf.d/ when starting the Docker Agent by mounting a /conf.d folder.

1. Create a configuration folder on the host with your YAML files:

   mkdir /opt/datadog-agent-conf.d
   touch /opt/datadog-agent-conf.d/http_check.yaml

2. When installing the Docker Agent, add -v /opt/datadog-agent-conf.d:/conf.d:ro, for example:

   DOCKER_CONTENT_TRUST=1 \
   docker run -d -v /var/run/docker.sock:/var/run/docker.sock:ro \
                 -v /proc/:/host/proc/:ro \
                 -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
                 -v /opt/datadog-agent-conf.d:/conf.d:ro \
                 -e DD_API_KEY=<YOUR_DATADOG_API_KEY> \
                 datadog/agent:latest

When the container starts, all files on the host in /opt/datadog-agent-conf.d with a .yaml extension are copied to /etc/datadog-agent/conf.d/. Note: If you add new YAML files to /opt/datadog-agent-conf.d, restart the Docker Agent.

The same can be done for the /checks.d folder. Any Python files in the /checks.d folder are automatically copied to /etc/datadog-agent/checks.d/ when starting the Docker Agent.

Further Reading

Additional helpful documentation, links, and articles:

Docker JMXDOCUMENTATION Collect your Docker logsDOCUMENTATION Collect your Docker processesDOCUMENTATION Collect your Docker tracesDOCUMENTATION