===== Datadog Docker Agent =====

The **Datadog Docker Agent** is a specialized version of the Datadog Agent designed to monitor Docker containers. It provides powerful insights into the performance, health, and resource utilization of your containers and the Docker environment. This agent helps you track various metrics, logs, and events for Docker containers and hosts, and integrates seamlessly with Datadog’s infrastructure monitoring platform.

==== 1. Overview ====

The Docker Agent collects various metrics from Docker containers and their associated infrastructure components. It is essential for users who want to monitor containerized applications, microservices, and Docker clusters. The agent runs as a container itself and provides visibility into:

- Resource usage (CPU, memory, disk, and network)
- Container lifecycle events
- Docker daemon metrics
- Logs generated by the containers

==== 2. Setting Up the Datadog Docker Agent ====

To set up the Datadog Docker Agent, you must deploy the agent container and configure it with the appropriate Datadog API key and any additional settings. 

- **Prerequisites**:
  - A Datadog account
  - A Docker environment (Docker Engine 1.10+)
  - An API key from Datadog

- **Step 1: Create a Datadog Agent container**:
Run the following Docker command to start the Datadog Agent container:
<code:bash>
  docker run -d --name datadog-agent \
    -e DD_API_KEY=<YOUR_DATADOG_API_KEY> \
    -e DD_SITE="datadoghq.com" \
    -e DD_DOCKER_HOST="unix:///var/run/docker.sock" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /proc:/host/proc:ro \
    -v /sys:/host/sys:ro \
    -v /cgroup:/host/cgroup:ro \
    --restart=unless-stopped \
    datadog/agent:latest
</code>    
Replace <YOUR_DATADOG_API_KEY> with your Datadog API key.

The -v /var/run/docker.sock:/var/run/docker.sock option allows the agent to monitor Docker containers by interacting with the Docker daemon.

Step 2: Verify the Agent: After starting the agent, check that it’s running properly by looking for the "Docker" section in the Datadog dashboard. If you’ve configured the agent correctly, you should start seeing metrics from your Docker environment.

    Step 3: Monitor Containers and Hosts: Once the Docker Agent is deployed, Datadog will automatically collect metrics related to the Docker containers, including:
        Container resource usage (CPU, memory, disk, network)
        Container events and status (start, stop, restarts, etc.)
        Docker daemon statistics
        Application-specific metrics (when instrumented with DogStatsD or Datadog API)

==== 3. Key Features of the Docker Agent ====

The Datadog Docker Agent provides several key features for monitoring containerized applications and infrastructure:

    Container Metrics: The Docker Agent collects detailed resource usage metrics for containers, including:
        CPU utilization
        Memory usage
        Disk I/O
        Network traffic

    Docker Daemon Metrics: The Docker Agent can also collect performance metrics related to the Docker daemon itself, such as:
        Number of containers running
        Docker events (e.g., container start/stop, restarts)
        Image usage and pull metrics

    Container Lifecycle Events: The Docker Agent captures events related to container lifecycle changes, such as:
        Container start/stop events
        Container restarts
        Health checks

    Logging: You can configure the Docker Agent to collect logs from running containers by setting up the log collection feature. Logs are sent to Datadog for further analysis and troubleshooting.

    Docker Compose Integration: The Datadog Agent integrates with Docker Compose, which is helpful for monitoring multi-container Docker applications. The agent can track the health of each service in the Docker Compose stack and provide detailed metrics for each container in the application.

    Container Tags: Tags can be used to assign metadata to your containers, making it easier to filter and group your containers in Datadog. Tags such as service, env, or version can be applied to your containers to track application-specific metrics.

==== 4. Configuration Options ====

You can customize the behavior of the Datadog Docker Agent using environment variables and configuration files. Here are some important configuration options:

    DD_API_KEY: Set your Datadog API key to authenticate the agent.

    DD_DOCKER_HOST: This variable specifies the location of the Docker socket. The default value is unix:///var/run/docker.sock, which should work for most environments.

    DD_DOCKER_CONTAINER_USE: This option controls whether container-level metrics are gathered. Set to true to collect metrics from Docker containers.

    DD_LOGS_ENABLED: Enable or disable log collection by setting this variable to true or false.

    DD_LOGS_CONFIG_CONTAINER_COLLECT_ALL: If you want to collect logs from all containers, set this variable to true.

    DD_HEALTH_PORT: Set the port where the agent health endpoint will be exposed.

Example Docker Agent Configuration:

docker run -d --name datadog-agent \
  -e DD_API_KEY=<YOUR_DATADOG_API_KEY> \
  -e DD_SITE="datadoghq.com" \
  -e DD_DOCKER_HOST="unix:///var/run/docker.sock" \
  -e DD_LOGS_ENABLED="true" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /proc:/host/proc:ro \
  -v /sys:/host/sys:ro \
  -v /cgroup:/host/cgroup:ro \
  --restart=unless-stopped \
  datadog/agent:latest

==== 5. Monitoring with the Docker Agent ====

Once the Docker Agent is set up, you can monitor various aspects of your Docker containers and Docker host directly from the Datadog platform. Some of the key metrics to monitor include:

    Container Resource Usage:
        docker.container.memory.usage
        docker.container.cpu.usage
        docker.container.disk.read
        docker.container.disk.write

    Docker Events:
        docker.event.start
        docker.event.stop
        docker.event.restart

    Docker Daemon Stats:
        docker.daemon.containers.running
        docker.daemon.containers.stopped

    Custom Metrics: If you are using Datadog’s DogStatsD or API, you can also monitor application-specific metrics from your containers.

You can view these metrics through Dashboards, Monitors, and Alerts in Datadog, allowing you to track the health of your containerized applications and take proactive actions.

==== 6. Troubleshooting ====

If the Docker Agent is not working as expected, here are some common troubleshooting steps:

    Verify Docker Socket Access: The agent requires access to the Docker socket (/var/run/docker.sock) to collect container metrics. Ensure the agent has the correct permissions to access the socket.

    Check Datadog Agent Logs: Review the Datadog Agent logs for any errors or issues. You can access the logs using the following command:

    docker logs datadog-agent

    Check Docker Daemon: Make sure that the Docker daemon is running correctly and that containers are started.

    Agent Configuration: Double-check that the agent is configured with the correct API key, Docker socket path, and other environment variables.

==== 7. Conclusion ====

The Datadog Docker Agent is a powerful tool for monitoring Docker containers and the Docker environment. It allows you to gain visibility into the resource usage, health, and performance of your containers and Docker hosts. With the Docker Agent, you can integrate container metrics and logs into Datadog’s unified monitoring platform for real-time insights and alerts.

For more details, refer to the official Datadog Docker Agent documentation.