Docker Monitoring: The Complete 2026 Guide
Monitor Docker containers properly — docker stats limits, cAdvisor + Prometheus setup, the container metrics that matter, log collection, and restart-loop alerting.
Short answer: docker stats is a flashlight, not a monitoring system — it shows live numbers with no history, no alerts, no multi-host view. Continuous Docker monitoring means collecting container metrics such as CPU throttling and memory via cAdvisor into Prometheus, retaining restart and OOM state from the runtime where available, collecting logs via a driver or Agent, and configuring alerts for OOM kills, restart loops, and CPU throttling. This guide gives you the commands, the compose file, and the alert rules for standalone Docker hosts; if you run Kubernetes, use the Kubernetes monitoring guide instead — related signals, with different collection and object models.
Step 0: Know your built-ins (and their limits)
docker stats # running containers by default; NET/BLOCK I/O are cumulative bytes
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"
docker inspect -f '{{.State.OOMKilled}} {{.State.Restarting}} {{.RestartCount}}' web
docker events --filter event=die # the death stream — useful for debugging, not alerting
docker logs --tail 100 -f web
These examples target Linux Docker Engine and a container named web; they require access to the relevant daemon. They answer "what is happening right now on this host." The moment you need "what happened last night" or "page me when a container restarts," you need continuous collection.
On Linux, roughly 100% CPU corresponds to one fully occupied logical CPU, so a multithreaded container can exceed 100%; it is not a percentage of its CPU quota. The CLI memory value subtracts part of the file cache, using total_inactive_file on cgroup v1 or inactive_file on v2 in current versions; Docker 19.03 and earlier used a different field. NET I/O and BLOCK I/O are cumulative bytes, not rates. The default list contains running containers, and PIDS includes kernel threads. Docker stats
The metrics that matter (and their container-specific traps)
| Metric | Source | The trap it catches |
|---|---|---|
container_cpu_cfs_throttled_seconds_total |
cAdvisor | Quota-related delays that can occur while the host has idle CPU; correlate with latency |
container_memory_working_set_bytes vs limit |
cAdvisor | Memory pressure relative to the limit; working set alone does not predict an OOM kill |
container_last_seen / OOMKilled flag |
cAdvisor timestamp / Docker Engine state | Stale or missing observations / recorded OOM state; these require different checks |
RestartCount changes for the same container ID |
Docker Engine inspect/API | Repeated restarts recorded by the runtime; replacement IDs need separate tracking |
container_fs_usage_bytes |
cAdvisor, where supported by the storage driver and mounts | Filesystem growth; distinguish the writable layer from volumes |
container_network_receive_errors_total / container_network_transmit_errors_total |
cAdvisor | Reported network errors; not proof of a particular NIC or overlay fault |
Image age / :latest drift |
Engine image metadata | Reproducibility and image-review signals; age alone does not establish patch status |
CPU throttling is worth charting next to CPU usage where the Linux CFS quota metrics are available. A container can hit its quota while the host still has idle CPU, delaying runnable work. Check the quota and request latency together; neither the host utilization nor the throttled counter alone establishes the cause of a slow request. Working set is likewise different from application heap or total memory charged to the cgroup. cAdvisor metric types
The reference stack: cAdvisor + Prometheus (+ Grafana)
# docker-compose.yml — standalone Linux monitoring example
services:
cadvisor:
image: ghcr.io/google/cadvisor:0.55.1
volumes:
- /:/rootfs:ro
- /var/run:/var/run:ro
- /sys:/sys:ro
- /var/lib/docker/:/var/lib/docker:ro
- /dev/disk/:/dev/disk:ro
privileged: true
devices: ["/dev/kmsg:/dev/kmsg"]
ports: ["127.0.0.1:8080:8080"]
prometheus:
image: prom/prometheus:latest
volumes: [ "./prometheus.yml:/etc/prometheus/prometheus.yml" ]
ports: ["127.0.0.1:9090:9090"]
grafana:
image: grafana/grafana:latest
ports: ["127.0.0.1:3000:3000"]
# prometheus.yml
scrape_configs:
- job_name: cadvisor
static_configs: [ { targets: ['cadvisor:8080'] } ]
# Optional host context: enable only after deploying Node Exporter
# on this Compose network; this stack does not deploy it.
# - job_name: node
# static_configs: [ { targets: ['node-exporter:9100'] } ]
This is a documented-configuration example, not an executed deployment result. cAdvisor v0.55.1 is pinned as an example; releases before v0.53.0 used the older image registry. Check the deployed version, cgroup support, Docker data-root and host paths. The mounts, device access and privileged mode follow the official Linux container example and grant substantial host access; they need review for the deployment environment. Host-specific paths may differ. Official cAdvisor deployment
The Prometheus and Grafana latest tags remain illustrative mutable tags; pin compatible versions or digests for a reproducible deployment. The example binds UIs to loopback and does not configure production storage, retention, authentication or backups. Configure persistent data and access controls separately. Grafana also needs a Prometheus data source using http://prometheus:9090 on this Compose network; localhost inside Grafana points back to Grafana. A dashboard is not provisioned by the Compose file. Grafana Docker configuration · Prometheus data source
After deployment, check http://127.0.0.1:9090/targets on the Docker host for a successful cAdvisor scrape, then inspect container_memory_working_set_bytes and the actual identity labels. Publishing a scrape target does not establish collection coverage for every container or metric.
Alert rules for standalone Docker hosts
# Recorded OOM events in the last 15 minutes, where this counter is collected
increase(container_oom_events_total[15m]) > 0
# More than 3 observed start-time changes on the same series in 30 minutes
changes(container_start_time_seconds[30m]) > 3
# More than 10% of recorded CFS periods were throttled (example threshold)
(rate(container_cpu_cfs_throttled_periods_total[5m])
/ rate(container_cpu_cfs_periods_total[5m]) > 0.10)
and (rate(container_cpu_cfs_periods_total[5m]) > 0)
# Working set above 85% of a positive reported limit (example threshold)
(container_memory_working_set_bytes / container_spec_memory_limit_bytes > 0.85)
and (container_spec_memory_limit_bytes > 0)
container_start_time_seconds is a gauge containing a timestamp, so increase() would not count restarts. changes() counts only value changes observed on the same series: it can miss restarts between scrapes and does not combine replacement container IDs. For restart-loop detection, retain Docker Engine restart state or runtime events with container identity. A container_last_seen check also needs missing-series handling; the timestamp is not an OOM event. Prometheus changes and increase
These are example expressions, not complete alert rules. Select the intended jobs and containers, verify metric availability and matching labels, and set duration, missing-data behavior and notification routing. The throttled-period ratio is a fraction of periods, not a fraction of wall-clock time. Apply the memory comparison to containers with verified finite limits: a positive reported value can still reflect host capacity rather than a configured container limit. Neither 10% nor 85% is a universal threshold.
Don't forget the logs
Metrics and runtime events can show that a container died; logs may explain the application behavior around it. If using json-file, set rotation to control disk growth. Use a compatible collector such as Fluent Bit or DataKit for the actual runtime and log format, rather than assuming every driver exposes readable JSON under /var/lib/docker/containers. Docker manages its own log files; do not manually modify or rotate them. Promtail reached end of life on March 2, 2026; use Alloy or another supported client for new setups. Docker logging drivers · Promtail lifecycle
For example, merge these options into the existing daemon configuration:
{ "log-driver": "json-file",
"log-opts": { "max-size": "10m", "max-file": "3" } }
The values in log-opts must be strings. Restart Docker Engine to apply a changed daemon default to newly created containers; existing containers do not inherit it automatically. Driver read support and the dual logging cache determine whether docker logs can read locally, and rotation can remove older records. JSON-file options · Dual logging
For structured applications, JSON on stdout gives a collector explicit fields to parse, provided field types and event time are configured correctly. Application files inside the container need an accessible file or volume path; they are not automatically included by docker logs. In Guance, the DataKit container collector collects supported container metrics, objects and stdout logs with configured runtime access. Standalone Docker collection follows the documented host installation and requires endpoint access and readable log paths; separate application files use the appropriate logging configuration. Preserve service, environment and container IDs across collection; old logs remain searchable only if they were collected and retained.
When to skip the DIY stack
The cAdvisor + Prometheus + Grafana stack can fit a Docker deployment when the team can operate collection, storage, dashboards and alerting. More hosts require suitable target discovery and capacity planning; a manual target list is not an inherent scaling limit of Prometheus. If the team also needs logs, host metrics and traces in an investigation, account for their collection and correlation work, along with retention and the availability of the monitoring backend.
An Agent-based platform changes that division of work. Guance's DataKit provides the documented container collection path described above; Datadog, New Relic and Grafana Cloud also offer Docker integrations. Check each destination's supported signals, field names, labels and query semantics. Existing PromQL and alert rules do not automatically transfer just because the container can send data to another platform. Datadog Docker integration · New Relic Docker monitoring · Grafana Cloud Docker integration
FAQ
Q: How do I monitor Docker containers?
Built-in: docker stats, docker events, docker logs, and docker inspect state fields cover live debugging. For real monitoring: run cAdvisor to expose per-container metrics, scrape with Prometheus, visualize in Grafana, and alert on OOM kills, restart loops, CPU throttling, and memory-vs-limit. Add log collection appropriate to the actual driver, paths and permissions; do not assume a universal Docker log directory.
Q: What is the difference between docker stats and cAdvisor?
docker stats streams live point-in-time numbers to your terminal — no storage, no history, no alerts, one host only. cAdvisor continuously collects supported container resource statistics and exposes metrics for Prometheus scraping. Its own observations do not configure long-term retention, dashboards or alerting: those belong to the backend and visualization stack. Coverage depends on cgroup/runtime support, enabled metrics, mounts and permissions. Neither tool aggregates application logs.
Q: How do I know if a container was OOM-killed?
docker inspect -f '{{.State.OOMKilled}}' web inspects that container's current recorded state, while docker events --filter event=oom can stream OOM events. Retain events externally for historical investigation; container replacement or later state changes can remove the context you expected to find. Where collected and supported, increase(container_oom_events_total[15m]) > 0 detects increments in the OOM counter. Host kernel logs may provide additional evidence if available and permitted. A restart alone does not establish OOM as its cause.
Q: What is CPU throttling in Docker?
Under a Linux CFS quota, runnable work can be delayed when the container consumes its allowed CPU time. container_cpu_cfs_throttled_seconds_total records throttled time where supported. This can happen while the host has spare CPU. Compare the quota, throttled-period ratio, CPU usage and request latency before changing the limit or workload. A 10% period threshold is only an example, and a high ratio does not quantify the application's latency impact.
Q: Should I use Docker monitoring tools or Kubernetes monitoring?
Match the orchestrator you run. Standalone Docker hosts / Docker Compose → cAdvisor + Prometheus stack in this guide. Kubernetes → distinguish the resource metrics pipeline, Kubernetes object-state metrics and kubelet/cAdvisor endpoints, configuring access and scraping for the signals you need. Swarm → use its service/task model and recovery behavior. These are different deployment models; Swarm usage alone does not establish a need to migrate. Kubernetes monitoring components · Swarm services
Sources: Docker documentation (stats, logging drivers, daemon.json), cAdvisor and Prometheus project docs linked above. Original source review dated 2026-08-07; technical corrections reviewed 2026-11-05. These examples were not executed for this article. Published by Guance; DataKit collection requires the runtime, permissions and signal configuration described above.
Contact us
Join the community
to join the community
Try Guance
Start online and pay only for what you use.
Get startedChoose a Guance plan
