How to Monitor Docker Containers with Datadog

Last verified: September 10, 2026
By: PerfMonitoring

The current Datadog Docker Agent can monitor a Docker host and discover containers when it is given access to the Docker runtime plus the host process and cgroup information it needs. Datadog recommends using the in-app installation flow, which generates a docker run command with the minimum configuration for your organization and optional feature toggles. [1]

This tutorial starts with metrics-only container monitoring. That is intentional. Logs and APM are useful, but enabling them at the same time adds mounts, network paths, data volume, and troubleshooting variables. First prove that the Agent can see your containers and send infrastructure telemetry; add logs or traces later if the use case requires them.

What You'll Accomplish

You will:

1. run one Datadog Agent 7 container on a Docker host;
2. understand why the Docker socket, /proc, and cgroup mounts are present;
3. verify the Agent from inside its container;
4. confirm that an application container is discovered in Datadog;
5. learn how container include/exclude filters affect metrics; and
6. troubleshoot socket, namespace, hostname, and connectivity problems.

Prerequisites

You need:

• a Datadog account and organization API key;
• the correct Datadog site for that organization;
• a Linux host running a supported Docker version;
• permission to run the Datadog Agent container with the host integrations documented below; and
• at least one application container running on the same Docker host.

This tutorial assumes the Docker Engine runtime. Datadog also supports containerd and Podman, but runtime-specific behavior and commands can differ. [1]

Quick Answer

Use Datadog's in-app Docker Agent installation flow whenever possible. The current manual Linux pattern runs registry.datadoghq.com/agent:7 with the host PID and cgroup namespaces, read-only mounts for the Docker socket, /proc, and /sys/fs/cgroup, plus DD_SITE and DD_API_KEY. After startup, run docker exec -it dd-agent agent status, then confirm that your application container appears with fresh metrics in Datadog. [1][2]

Step 1: Understand the Minimum Docker Agent Architecture

For Docker monitoring, the Agent is itself a container, but it needs visibility beyond its own isolated filesystem and namespaces.

The current Datadog command uses:

• --cgroupns host so the Agent uses the host cgroup namespace;
• --pid host so it can observe the host PID namespace as required by the documented container setup;
• /var/run/docker.sock to query the Docker runtime and discover container metadata;
• /proc/ mounted at /host/proc/ for host process/system information; and
• /sys/fs/cgroup/ mounted at /host/sys/fs/cgroup/ for cgroup data. [1]

The three bind mounts in the base command are read-only, which helps avoid accidental file modification. However, access to the Docker socket should still be treated as security-sensitive. A process that can talk to the Docker daemon has substantial visibility and potentially powerful control over the host depending on daemon/API permissions. Do not expose the socket to arbitrary application containers.

Step 2: Run the Datadog Agent Container

Datadog recommends its in-app flow first. If you need to understand the manual baseline, the current documentation shows this pattern for Linux: [1]

docker run -d --cgroupns host --pid host --name dd-agent \
  -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_SITE=<DATADOG_SITE> \
  -e DD_API_KEY=<DATADOG_API_KEY> \
  registry.datadoghq.com/agent:7

Replace both placeholders with values from your own Datadog organization. Do not publish the API key in a Compose file committed to a public repository.

For an operational deployment, inject the key through your approved secrets mechanism rather than baking it into an image. The exact mechanism depends on whether you use Docker Compose, Swarm, a secret manager, or host-level automation.

Datadog's documentation says to run the Agent container once on each host you want to monitor. Do not start multiple independent Datadog Agents on the same Docker node just because you are adding another application container. [1]

Check that the Agent container started:

docker ps --filter name=dd-agent

If it exited, inspect its logs before changing several settings at once:

docker logs dd-agent

Step 3: Verify the Agent from Inside the Container

Datadog documents the Docker Agent status command as: [2]

docker exec -it dd-agent agent status

The output is the container equivalent of the Linux host Agent status page. Review it for persistent errors, forwarder problems, and container/Docker-related checks.

A useful verification sequence is:

docker ps --filter name=dd-agent
docker exec -it dd-agent agent status

The first command answers “is the container running?” The second answers the more important question: “is the Agent inside it healthy enough to collect and forward telemetry?”

If docker exec fails because the container repeatedly exits, go back to docker logs dd-agent and fix the startup problem first.

Step 4: Confirm That Datadog Discovers a Real Application Container

Make sure at least one non-Agent application container is running:

docker ps

In Datadog, open the infrastructure/container view and look for that container or its image/service metadata. Navigation can change over time, so the success criterion is more durable than the menu label: the container should appear with a recent timestamp and updating resource metrics.

Check more than the mere existence of an entity. Confirm that:

• the container name or service identity matches your Docker host;
• CPU/memory or other expected container metrics update over time;
• the host relationship is correct; and
• tags/labels are usable for filtering.

If the Agent appears but the application container does not, inspect the Agent status and any container inclusion/exclusion rules before assuming the Datadog backend is at fault.

Step 5: Use Container Filters Deliberately

Datadog Agent 7 supports environment variables for including or excluding containers from metrics/log collection and Autodiscovery. Current documentation includes variables such as DD_CONTAINER_EXCLUDE, DD_CONTAINER_EXCLUDE_METRICS, DD_CONTAINER_INCLUDE, and DD_CONTAINER_INCLUDE_METRICS. [3]

For example, Datadog documents excluding a container by name with a regular-expression-style filter. A practical use is preventing the monitoring Agent itself from becoming noise in a view intended for application workloads.

Do not begin with a broad exclude rule unless you can explain exactly what it matches. Inclusion/exclusion rules can make a healthy Agent look “broken” simply because it has been told not to collect a container's metrics.

When debugging missing containers, temporarily simplify the filters and confirm discovery before reintroducing complex matching logic.

Step 6: Decide Whether You Actually Need Logs or APM

The base command above is deliberately focused on infrastructure/container metrics.

Container logs

Datadog's Docker log-collection documentation adds DD_LOGS_ENABLED=true, log-selection settings, and a read-only mount of /var/lib/docker/containers for the Docker JSON log files. [4]

That is a separate decision. Before enabling “collect all container logs,” consider:

• data volume and cost implications;
• secrets or personal data that applications may write to logs;
• whether every container should be collected; and
• whether labels-based selective collection is more appropriate.

APM traces

Datadog's Docker APM documentation describes additional Agent configuration and application instrumentation. Trace collection is not proven merely because Docker infrastructure metrics work. [5]

Keep these layers separate during initial troubleshooting. If metrics, logs, and traces all fail at once, you have three data paths to diagnose instead of one.

Verify the Setup

Use all of the following checks:

1. docker ps --filter name=dd-agent shows the Agent container running.
2. docker exec -it dd-agent agent status completes and does not show a persistent forwarding or container-runtime failure.
3. docker ps shows at least one application container you expect Datadog to discover.
4. The same application container appears in Datadog with fresh resource telemetry.
5. Container tags/labels allow you to distinguish the workload from unrelated containers.

For a stronger test, start a harmless short-lived container and confirm that Datadog eventually observes it according to the product's normal collection behavior. Do not claim an exact appearance delay unless you measure it in your own environment.

Common Problems and Fixes

Problem: The Agent cannot access /var/run/docker.sock

Cause: the socket is missing, mounted at the wrong path, the runtime is not Docker, or permissions/runtime security controls prevent access.

Fix: confirm the host socket exists and that your docker run command matches the current Datadog Docker documentation. If you are actually using containerd or Podman, follow the runtime-specific path instead of forcing a Docker socket configuration. [1]

Problem: The Agent runs, but no application containers appear

Cause: inclusion/exclusion filters, missing Docker socket visibility, namespace/mount mismatch, or incorrect runtime assumptions.

Fix: inspect agent status, review DD_CONTAINER_* variables, and compare your launch command with Datadog's current minimal Docker Agent command. Remove nonessential filters during diagnosis.

Problem: Host or process metrics are incomplete

Cause: missing /proc or cgroup mount, omitted host namespace settings, or a host/runtime layout different from the documented Linux baseline.

Fix: verify --cgroupns host, --pid host, /proc/:/host/proc/:ro, and /sys/fs/cgroup/:/host/sys/fs/cgroup:ro against the current documentation. [1]

Do not copy old Amazon Linux cgroup paths into a modern host without confirming that they apply to your OS.

Problem: The Agent sends data to the wrong Datadog organization or nowhere

Cause: DD_SITE or DD_API_KEY is wrong, or outbound network access is blocked.

Fix: use the values from your own Datadog installation workflow, then inspect agent status and Agent logs. A syntactically valid docker run command can still target the wrong Datadog site.

Problem: Logs are missing even though container metrics work

Cause: expected behavior if you deployed only the metrics baseline from this tutorial.

Fix: follow the current Docker log-collection documentation and add the required settings/mounts intentionally. Do not interpret “metrics work, logs do not” as a Docker discovery failure when log collection has not been enabled. [4]

Best Practices

Run one Agent per Docker host. This matches Datadog's documented model and keeps host/container identity predictable. [1]

Treat the Docker socket as privileged. Mount it only into the monitoring Agent or other components that genuinely require it, and protect access to the Agent container itself.

Use a major-version tag deliberately. Datadog's current baseline example uses registry.datadoghq.com/agent:7. For stricter change control, define an upgrade policy appropriate to your environment rather than relying on an unreviewed image update.

Start with metrics. Add logs/APM after basic discovery and forwarding work. Layered rollout makes failures easier to isolate.

Filter with intent. Exclude noisy or irrelevant containers only when you understand how the rule affects metrics, logs, and Autodiscovery. Datadog provides global and signal-specific filters; they are not interchangeable in every case. [3]

Use stable service metadata. Consistent tags and Docker labels make it easier to group containers across restarts and hosts than relying on ephemeral container IDs.

When This Setup Makes Sense

This approach is appropriate when you operate Docker Engine hosts directly and want host plus container infrastructure visibility from Datadog.

If your containers run primarily under Kubernetes, use Datadog's Kubernetes deployment path rather than treating every Kubernetes node as a standalone Docker host. If you only need host-level Linux metrics without container discovery, use the standard Linux Agent installation described in How to Set Up Datadog Infrastructure Monitoring.

For broader context, see PerfMonitoring's Datadog software profile, infrastructure monitoring guide, server monitoring category, and Datadog vs Dynatrace comparison.

FAQ

Why does Datadog need access to the Docker socket?

The Agent uses the Docker runtime interface to discover containers and their metadata. Without the runtime view, a containerized Agent does not automatically know what every sibling container on the host is doing. The socket is security-sensitive, so access should be tightly controlled.

Can I monitor Docker without collecting container logs?

Yes. The base Docker Agent setup can collect infrastructure/container telemetry without enabling Docker log collection. Datadog documents log collection as an additional configuration with extra environment variables and mounts. [4]

Why are some containers missing from Datadog?

Check the Agent's Docker/runtime access first, then review DD_CONTAINER_INCLUDE* and DD_CONTAINER_EXCLUDE* rules. A filter can intentionally prevent metrics or logs from being collected even when the Agent itself is healthy. [3]

Conclusion

Successful Datadog Docker monitoring is more than a running Agent container. The Agent must have the documented host/runtime visibility, be able to forward telemetry to the correct Datadog site, and discover a real application container with fresh metrics.

Start with the smallest metrics-only deployment, validate it end to end, then add log collection, APM, or additional integrations as separate changes. That sequence gives you a much clearer troubleshooting path and a more controlled security/data-volume profile.

References

1. Datadog Documentation — Docker Agent for Docker, containerd, and Podman — https://docs.datadoghq.com/containers/docker/ — accessed September 10, 2026.
2. Datadog Documentation — Agent Commands — https://docs.datadoghq.com/agent/configuration/agent-commands/ — accessed September 10, 2026.
3. Datadog Documentation — Container Discovery Management — https://docs.datadoghq.com/containers/guide/container-discovery-management/ — accessed September 10, 2026.
4. Datadog Documentation — Docker Log collection — https://docs.datadoghq.com/containers/docker/log/ — accessed September 10, 2026.
5. Datadog Documentation — Tracing Docker Applications — https://docs.datadoghq.com/containers/docker/apm/ — accessed September 10, 2026.

Editorial note: This tutorial was checked against current official Datadog documentation on the date above. No live Datadog organization or Docker production host was used to claim hands-on test results.