Note: AD Annotations v2 was introduced in Datadog Agent 7.36 to simplify integration configuration. For previous versions of the Datadog Agent, use AD Annotations v1.
To automatically enable Autodiscovery over Docker containers, mount /var/run/docker.sock
into the containerized Agent. On Windows, mount \\.\pipe\docker_engine
.
Integrations templates can be stored as Docker labels. With Autodiscovery, the Agent detects if it’s running on Docker and automatically searches all labels for integration templates. Autodiscovery expects labels to look like the following examples:
Dockerfile:
LABEL "com.datadoghq.ad.checks"='{"<INTEGRATION_NAME>": {"instances": [<INSTANCE_CONFIG>]}}'
docker-compose.yaml:
labels:
com.datadoghq.ad.checks: '{"<INTEGRATION_NAME>": {"instances": [<INSTANCE_CONFIG>]}}'
Using docker run
, nerdctl run
, or podman run
commands:
-l com.datadoghq.ad.checks="{\"<INTEGRATION_NAME>\": {\"instances\": [<INSTANCE_CONFIG>]}}"
Note: You can escape JSON while configuring these labels. For example:
docker run --label "com.datadoghq.ad.checks="{\"apache\": {\"instances\": [{\"apache_status_url\":\"http://%%host%%/server-status?auto2\"}]}}"
Docker Swarm:
When using Swarm mode for Docker Cloud, labels must be applied to the image:
version: "1.0"
services:
...
project:
image: '<IMAGE_NAME>'
labels:
com.datadoghq.ad.checks: '{"<INTEGRATION_NAME>": {"instances": [<INSTANCE_CONFIG>]}}'
Note: When configuring Autodiscovery, Datadog recommends using Docker labels to unify telemetry across your containerized environment. Read the unified service tagging documentation for more information.
To automatically enable Autodiscovery over Docker containers, mount /var/run/docker.sock
into the Containerized Agent. On Windows, mount \\.\pipe\docker_engine
.
Integrations templates can be stored as Docker labels. With Autodiscovery, the Agent detects if it’s running on Docker and automatically searches all labels for integration templates. Autodiscovery expects labels to look like the following examples:
Dockerfile:
LABEL "com.datadoghq.ad.check_names"='[<INTEGRATION_NAME>]'
LABEL "com.datadoghq.ad.init_configs"='[<INIT_CONFIG>]'
LABEL "com.datadoghq.ad.instances"='[<INSTANCE_CONFIG>]'
docker-compose.yaml:
labels:
com.datadoghq.ad.check_names: '[<INTEGRATION_NAME>]'
com.datadoghq.ad.init_configs: '[<INIT_CONFIG>]'
com.datadoghq.ad.instances: '[<INSTANCE_CONFIG>]'
Using docker run
, nerdctl run
, or podman run
commands:
-l com.datadoghq.ad.check_names='[<INTEGRATION_NAME>]' -l com.datadoghq.ad.init_configs='[<INIT_CONFIG>]' -l com.datadoghq.ad.instances='[<INSTANCE_CONFIG>]'
Note: You can escape JSON while configuring these labels. For example:
docker run --label "com.datadoghq.ad.check_names=[\"redisdb\"]" --label "com.datadoghq.ad.init_configs=[{}]" --label "com.datadoghq.ad.instances=[{\"host\":\"%%host%%\",\"port\":6379}]" --label "com.datadoghq.ad.logs=[{\"source\":\"redis\"}]" --name redis redis
Docker Swarm:
When using Swarm mode for Docker Cloud, labels must be applied to the image:
version: "1.0"
services:
...
project:
image: '<IMAGE_NAME>'
labels:
com.datadoghq.ad.check_names: '[<INTEGRATION_NAME>]'
com.datadoghq.ad.init_configs: '[<INIT_CONFIG>]'
com.datadoghq.ad.instances: '[<INSTANCE_CONFIG>]'
Note: When configuring autodiscovery, Datadog recommends using Docker labels to unify telemetry across your containerized environment. Read the unified service tagging documentation for more information.
Storing templates as local files and mounting them inside the containerized Agent doesn’t require an external service or a specific orchestration platform. The downside is that you need to restart your Agent containers each time you change, add, or remove templates. The Agent looks for Autodiscovery templates in the mounted /conf.d
directory.
Since Agent v6.2.0 (and v5.24.0), the default templates use the default port for the monitored software, instead of auto-detecting it. If you need to use a different port, provide a custom Autodiscovery template in the Docker container labels
These integration templates are meant for basic cases. If you need a custom Datadog integration configuration to enable extra options, use different container identifiers—or use template variables indexing and write your own auto-configuration file:
- Create a
conf.d/<INTEGRATION_NAME>.d/conf.yaml
file on your host and add your custom auto-configuration. - Mount your host
conf.d/
folder to the containerized Agent’s conf.d
folder.
Example auto-configuration file:
ad_identifiers:
<INTEGRATION_AUTODISCOVERY_IDENTIFIER>
init_config:
<INIT_CONFIG>
instances:
<INSTANCES_CONFIG>
See the Autodiscovery Container Identifiers documentation for information on the <INTEGRATION_AUTODISCOVERY_IDENTIFIER>
.
Note: You don’t need to set up the <INTEGRATIONS_NAME>
since the Agent infers it from the file name directly.
Autodiscovery can use Consul, Etcd, and Zookeeper as integration template sources. To use a key-value store, configure it in the Agent datadog.yaml
configuration file and mount this file inside the containerized Agent. Alternatively, pass your key-value store as environment variables to the containerized Agent.
Configure in datadog.yaml:
In the datadog.yaml
file, set the <KEY_VALUE_STORE_IP>
address and <KEY_VALUE_STORE_PORT>
of your key-value store:
config_providers:
- name: etcd
polling: true
template_dir: /datadog/check_configs
template_url: '<KV_STORE_IP>:<KV_STORE_PORT>'
username:
password:
- name: consul
polling: true
template_dir: datadog/check_configs
template_url: '<KV_STORE_IP>:<KV_STORE_PORT>'
ca_file:
ca_path:
cert_file:
key_file:
username:
password:
token:
- name: zookeeper
polling: true
template_dir: /datadog/check_configs
template_url: '<KV_STORE_IP>:<KV_STORE_PORT>'
username:
password:
Then restart the Agent to apply the configuration change.
Configure in environment variables:
With the key-value store enabled as a template source, the Agent looks for templates under the key /datadog/check_configs
. Autodiscovery expects a key-value hierarchy like this:
/datadog/
check_configs/
<CONTAINER_IDENTIFIER>/
- check_names: ["<INTEGRATION_NAME>"]
- init_configs: ["<INIT_CONFIG>"]
- instances: ["<INSTANCE_CONFIG>"]
...
Note: To apply a specific configuration to a given container, Autodiscovery identifies containers by image when using the key-value stores by trying to match <CONTAINER_IDENTIFIER>
to .spec.containers[0].image
.