How to Add the Datadog Agent to Your Docker Container: A Practical Guide

Monitoring your applications and infrastructure is crucial for understanding system health, performance, and ensuring reliability. Datadog is a powerful monitoring service that collects metrics, logs, and traces from your environments. If you’re running your apps inside Docker containers, adding the Datadog agent might seem tricky at first — but it’s simpler than you think.

In this post, I’ll walk you through how to add the Datadog agent to your Docker container environment so you can start collecting valuable telemetry data quickly.

Why Add Datadog Agent to Docker Containers?

Containers are ephemeral by nature; they spin up and down frequently. Running the Datadog agent inside or alongside your containers allows you to:

Collect metrics about container resource usage (CPU, memory, IO).
Monitor application-level stats via integrations.
Centralize logs and traces for troubleshooting.
Get alerts on anomalies in your containerized apps.

Two Common Approaches

Run a standalone Datadog Agent container alongside your app containers (sidecar pattern).
Install and run the Datadog Agent inside your application Docker image itself.

Both have pros and cons—sidecar isolates monitoring from app code but requires managing multiple containers; installing inside the app container reduces complexity but can increase image size.

This guide focuses mainly on approach #2 — embedding the Datadog Agent within your container.

Prerequisites

A Datadog account
Your Datadog API key
Docker installed locally or on your environment
Basic knowledge of Dockerfiles and docker-compose

Step 1: Create or Update Your Dockerfile to Include Datadog Agent

You can install the official Datadog Agent directly inside your container during build time. Here’s a minimal example using an Ubuntu-based image.

# Start with an official base image
FROM ubuntu:20.04

# Install dependencies
RUN apt-get update && apt-get install -y curl gnupg apt-transport-https

# Add the Datadog repository and install agent
RUN DD_AGENT_MAJOR_VERSION=7 \
    && DD_API_KEY=YOUR_DATADOG_API_KEY \
    && echo "deb https://apt.datadoghq.com/ stable 7" | tee /etc/apt/sources.list.d/datadog.list \
    && curl -L https://keys.datadoghq.com/DATADOG_APT_KEY.public | apt-key add - \
    && apt-get update \
    && apt-get install -y datadog-agent

# Configure the agent with your API key (we will use env variables instead)
ENV DD_API_KEY=YOUR_DATADOG_API_KEY
ENV DD_SITE="datadoghq.com"

# Copy your application code (simulate with placeholder)
COPY . /app
WORKDIR /app

# Start the agent in the background when container starts
CMD service datadog-agent start && ./start-my-app.sh

Notes:

Replace YOUR_DATADOG_API_KEY with an environment variable at runtime instead of hardcoding.
DD_SITE changes if you are using datadoghq.eu or another regional site.
The datadog-agent package is installed via Apt from Datadog’s official repo.
The command starts both the datadog-agent service and then launches your app script.

Step 2: Pass Your API Key Securely at Runtime

Hardcoding API keys in images is insecure. Use environment variables instead.

Example docker run command:

docker build -t my-app-with-datadog .
docker run -d \
  -e DD_API_KEY=your_actual_api_key_here \
  my-app-with-datadog

Or via a docker-compose file:

version: "3"
services:
  app:
    build: .
    environment:
      - DD_API_KEY=your_actual_api_key_here
      - DD_SITE=datadoghq.com

Step 3: Configure Additional Integrations (Optional)

Datadog supports many integrations (Nginx, Redis, MySQL etc.) via config files under /etc/datadog-agent/conf.d.

You can add config files to your Docker image or mount them as volumes.

Example for enabling Nginx integration:

COPY nginx.d/conf.yaml /etc/datadog-agent/conf.d/nginx.d/conf.yaml

Example config snippet (nginx.d/conf.yaml):

init_config:

instances:
  - nginx_status_url: http://localhost/nginx_status/

Step 4: Build & Run Your Container — Verify Agent is Running

Build image:

docker build -t my-app-with-datadog .

Run container with API key:

docker run --rm -e DD_API_KEY=your_api_key_here my-app-with-datadog

To check if the agent is running inside:

docker exec <container_id_or_name> datadog-agent status

You should see detailed metrics and info about collected integrations.

Bonus: Use Hosted Agent Container Instead (Sidecar Pattern)

If you prefer keeping monitoring separate from app containers, use the official datadog/agent image side-by-side.

Example docker-compose snippet:

version: '3'
services:
  app:
    image: my-app-image
    ports:
      - "8000:8000"

  datadog-agent:
    image: gcr.io/datadoghq/agent:latest
    environment:
      - DD_API_KEY=your_api_key_here
      - DD_SITE=datadoghq.com 
      - ECS_FARGATE=true # Example env, set as applicable 
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro # Required for container monitoring 
      - /proc/:/host/proc/:ro 
      - /sys/fs/cgroup/:/host/sys/fs/cgroup:ro

This lets the agent monitor all running containers on that host.

Conclusion

Adding the Datadog Agent into your Docker containers gives you invaluable insights into what’s happening under the hood of your apps. Whether embedding it within your Dockerfile or running it as a sidecar container alongside your app, it’s straightforward once you know how.

Start by securely passing along your API keys as env variables, ensure proper configuration of integrations if needed, then verify that metrics reach the Datadog dashboard.

Happy monitoring!

Feel free to ask any questions or share experiences in comments!

References & Helpful Links

Official Datadog Agent for Docker docs: https://docs.datadoghq.com/agent/docker/
Example integrations config files: https://github.com/DataDog/integrations-core/tree/master/nginx/conf.yaml.example
Datadog best practices for container monitoring

If you want me to tailor this content further or add specific code language examples like Python apps or Node.js integration — just let me know!

Add Datadog Agent To Docker Container