New announcements for Serverless, Network, RUM, and more from Dash! New announcements from Dash!

Docker Agent

Overview

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

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=<YOUR_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=<YOUR_DATADOG_API_KEY> \
                              datadog/agent:latest

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
Env VariableDescription
DD_API_KEYYour Datadog API key (required)
DD_HOSTNAMEHostname to use for metrics (if autodetection fails)
DD_TAGSHost tags separated by spaces. For example: simple-tag-0 tag-key-1:tag-value-1
DD_SITEDestination 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.
Optional collection Agents

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

Env VariableDescription
DD_APM_ENABLEDEnable trace collection with the trace Agent.
DD_LOGS_ENABLEDEnable log collection with the logs Agent.
DD_PROCESS_AGENT_ENABLEDEnable 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 VariableDescription
DD_DOGSTATSD_NON_LOCAL_TRAFFICListen to DogStatsD packets from other containers (required to send custom metrics).
DD_HISTOGRAM_PERCENTILESThe histogram percentiles to compute (separated by spaces). The default is “0.95”.
DD_HISTOGRAM_AGGREGATESThe histogram aggregates to compute (separated by spaces). The default is “max median avg count”.
DD_DOGSTATSD_SOCKETPath to the unix socket to listen to. Must be in a rw mounted volume.
DD_DOGSTATSD_ORIGIN_DETECTIONEnable container detection and tagging for unix socket metrics.

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:

Env 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_KUBERNETES_POD_ANNOTATIONS_AS_TAGSExtract pod annotations
DD_COLLECT_EC2_TAGSExtract custom EC2 tags without using the AWS integration

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.

Ignore containers

Exclude containers from logs collection, metrics collection, and Autodiscovery. Datadog excludes Kubernetes and OpenShift pause containers by default.

Env VariableDescription
DD_AC_INCLUDEWhitelist of containers to include (separated by spaces). Use .* to include all. For example: "image:image_name_1 image:image_name_2", image:.*
DD_AC_EXCLUDEBlacklist 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 VariableDescription
DD_PROCESS_AGENT_CONTAINER_SOURCEOverrides container source auto-detection to force a single source. e.g "docker", "ecs_fargate", "kubelet"
DD_HEALTH_PORTSet this to 5555 to expose the Agent health check at port 5555.

Validation

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

Commands

These commands are run on the host.

TypeCommand
StartUse the installation command.
Stopdocker exec -it <CONTAINER_NAME> agent stop
RestartUse the installation command.
Statusdocker exec -it <CONTAINER_NAME> agent status

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.

CheckMetrics
CPUSystem
DiskDisk
DockerDocker
File HandleSystem
IOSystem
LoadSystem
MemorySystem
NetworkNetwork
NTPNTP
UptimeSystem

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