Docker and Integrations

This page covers how to install and configure integrations for your Docker infrastructure by using a Datadog feature known as Autodiscovery. Autodiscovery enables you to use variables like %%host%% to dynamically populate your configuration settings.

For a detailed explanation of how Autodiscovery works, see Getting Started with Containers: Autodiscovery. For advanced Autodiscovery options, such as excluding certain containers from Autodiscovery or tolerating unready pods, see Container Discovery Management.

If you are using Kubernetes, see Kubernetes and Integrations.

The following Datadog integrations don't work with Autodiscovery because they require either process tree data or filesystem access: Ceph, Varnish, Postfix, Cassandra Nodetool, and Gunicorn.

To monitor integrations that are not compatible with Autodiscovery, you can use a Prometheus exporter in the pod to expose an HTTP endpoint, and then use the OpenMetrics integration (which supports Autodiscovery) to find the pod and query the endpoint.

Set up your integration

Some integrations require setup steps, such as creating an access token or granting read permission to the Datadog Agent. Follow the instructions in the Setup section of your integration’s documentation.

Community integrations

To use an integration that is not packaged with the Datadog Agent, you must build a custom image that contains your desired integration. See Use Community Integrations for instructions.

Configuration

Some commonly-used integrations come with default configuration for Autodiscovery. See Autodiscovery auto-configuration for details, including a list of auto-configured integrations and their corresponding default configuration files. If your integration is in this list, and the default configuration is sufficient for your use case, no further action is required.

Otherwise:

  1. Choose a configuration method (Docker labels, a local file, or a key-value store) that suits your use case.
  2. Reference the template format for your chosen method. Each format contains placeholders, such as <CONTAINER_IMAGE>.
  3. Supply values for these placeholders.

Dockerfile

For Datadog Agent v7.36+:

LABEL "com.datadoghq.ad.checks"='{"<INTEGRATION_NAME>": {"instances": [<INSTANCE_CONFIG>], "logs": [<LOGS_CONFIG>]}}'

For earlier Agent versions:

LABEL "com.datadoghq.ad.check_names"='[<INTEGRATION_NAME>]'
LABEL "com.datadoghq.ad.init_configs"='[<INIT_CONFIG>]'
LABEL "com.datadoghq.ad.instances"='[<INSTANCE_CONFIG>]'
LABEL "com.datadoghq.ad.logs"='[<LOGS_CONFIG>]'

docker-compose.yaml

For Datadog Agent v7.36+:

labels:
  com.datadoghq.ad.checks: '{"<INTEGRATION_NAME>": {"instances": [<INSTANCE_CONFIG>], "logs": [<LOGS_CONFIG>]}}'

For earlier Agent versions:

labels:
  com.datadoghq.ad.check_names: '[<INTEGRATION_NAME>]'
  com.datadoghq.ad.init_configs: '[<INIT_CONFIG>]'
  com.datadoghq.ad.instances: '[<INSTANCE_CONFIG>]'
  com.datadoghq.ad.logs: '[<LOGS_CONFIG>]'

Using docker run, nerdctl run, or podman run

For Datadog Agent v7.36+:

docker run -l com.datadoghq.ad.checks="{\"<INTEGRATION_NAME>\": {\"instances\": [<INSTANCE_CONFIG>], \"logs\": [<LOGS_CONFIG>]}}"

For earlier Agent versions:

docker run -l com.datadoghq.ad.check_names='[<INTEGRATION_NAME>]' -l com.datadoghq.ad.init_configs='[<INIT_CONFIG>]' -l com.datadoghq.ad.instances='[<INSTANCE_CONFIG>]' -l com.datadoghq.ad.logs='[<LOGS_CONFIG>]'

Note: You can escape JSON while configuring these labels. For example:

docker run -l "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.

For Datadog Agent v7.36+:

version: "1.0"
services:
...
  project:
    image: '<IMAGE_NAME>'
    labels:
      com.datadoghq.ad.checks: '{"<INTEGRATION_NAME>": {"instances": [<INSTANCE_CONFIG>], "logs": [<LOGS_CONFIG>]}}'

For earlier Agent versions:

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>]'
      com.datadoghq.ad.logs: '[<LOGS_CONFIG>]'

You can store Autodiscovery templates as local files inside the mounted /conf.d directory. You must restart your Agent containers each time you change, add, or remove templates.

  1. Create a conf.d/<INTEGRATION_NAME>.d/conf.yaml file on your host:

    ad_identifiers:
  - <CONTAINER_IMAGE>

init_config:
  <INIT_CONFIG>

instances:
  <INSTANCES_CONFIG>

logs:
  <LOGS_CONFIG>

  2. Mount your host conf.d/ folder to the containerized Agent’s conf.d folder.

You can source Autodiscovery templates from Consul, etcd, or ZooKeeper. You can configure your key-value store in the datadog.yaml configuration file (and subsequently mount this file inside the Agent container), or as environment variables in the Agent container.

Configure in datadog.yaml:

In datadog.yaml, 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:

Restart the Datadog Agent to apply your changes.

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_IMAGE>/
      - check_names: ["<INTEGRATION_NAME>"]
      - init_configs: ["<INIT_CONFIG>"]
      - instances: ["<INSTANCES_CONFIG>"]
      - logs: ["<LOGS_CONFIG>"]
    ...

Placeholder values

Supply placeholder values as follows:

<INTEGRATION_NAME>
The name of your Datadog integration, such as etcd or redisdb.
<CONTAINER_IMAGE>
An identifier to match against the container image.

For example: if you supply redis as a container identifier, your Autodiscovery template is applied to all containers with image names that match redis. If you have one container running foo/redis:latest and bar/redis:v2, your Autodiscovery template is applied to both containers.

The ad_identifiers parameter takes a list, so you can supply multiple container identifiers. You can also use custom identifiers. See Custom Autodiscovery Identifiers.
<INIT_CONFIG>
The configuration parameters listed under init_config in your integration’s <INTEGRATION_NAME>.d/conf.yaml.example file. The init_config section is usually empty.
<INSTANCES_CONFIG>
The configuration parameters listed under instances in your integration’s <INTEGRATION_NAME>.d/conf.yaml.example file.
<LOGS_CONFIG>
The configuration parameters listed under logs in your integration’s <INTEGRATION_NAME>.d/conf.yaml.example file.

Examples

Redis integration

Redis is one the technologies for which Autodiscovery auto-configuration is available. The following examples demonstrate overriding this basic configuration with a custom configuration that supplies a password parameter.

Store your password as an environment variable named REDIS_PASSWORD; then:

For Datadog Agent v7.36+:

labels:
  com.datadoghq.ad.checks: '{"redisdb": {"instances": [{"host": "%%host%%","port":"6379","password":"%%env_REDIS_PASSWORD%%"}], "logs": [{"type": "file", "path": "/var/log/redis_6379.log", "source": "redis", "service": "redis_service"}]}}'

For earlier Agent versions:

labels:
  com.datadoghq.ad.check_names: '["redisdb"]'
  com.datadoghq.ad.init_configs: '[{}]'
  com.datadoghq.ad.instances: '[{"host": "%%host%%","port":"6379","password":"%%env_REDIS_PASSWORD%%"}]'
  com.datadoghq.ad.logs: '[{"type": "file", "path": "/var/log/redis_6379.log", "source": "redis", "service": "redis_service"}]'

  1. Create a conf.d/redisdb.d/conf.yaml file on your host:

    ad_identifiers:
  - redis
init config:
instances:
  - host: "%%host%%"
    port: "6379"
    username: "datadog"
    password: "%%env_REDIS_PASSWORD%%"
logs:
  - type: "file"
    path: "/var/log/redis.log"
    source: "redis"
    service: "redis_service"

  2. Mount your host conf.d/ folder to the containerized Agent’s conf.d folder.

The following etcd commands create a Redis integration template with a custom password parameter:

etcdctl mkdir /datadog/check_configs/redis
etcdctl set /datadog/check_configs/redis/check_names '["redisdb"]'
etcdctl set /datadog/check_configs/redis/init_configs '[{}]'
etcdctl set /datadog/check_configs/redis/instances '[{"host": "%%host%%","port":"6379","password":"%%env_REDIS_PASSWORD%%"}]'

Notice that each of the three values is a list. Autodiscovery assembles list items into the integration configurations based on shared list indexes. In this case, it composes the first (and only) check configuration from check_names[0], init_configs[0] and instances[0].

All of these examples use Autodiscovery template variables:

  • %%host%% is dynamically populated with the container’s IP.
  • %%env_REDIS_PASSWORD%% references an environment variable named REDIS_PASSWORD as seen by the Agent process.

For more examples, including how to configure multiple checks for multiple sets of containers, see Autodiscovery: Scenarios & Examples.

PREVIEWING: aliciascott/DOCS-9725-Cloudcraft