Stats, Events, and Inspection

When driftwood/web is slow or restarting, three built-in tools answer different questions without any external monitoring stack. docker stats shows live resource use, docker events streams what the daemon is doing as it happens, and docker inspect dumps the full runtime state of a container — including why it stopped. Add docker top for the process list inside a container, and you have enough to diagnose an OOM kill or a restart loop on one host before reaching for Prometheus.

The discipline these four enforce is to stop guessing. A container that keeps dying has a cause that is observable: an exit code, a memory column climbing toward a limit, a repeating event cycle. The mistake is to read the application code looking for a bug when the kernel killed the process for exceeding its memory cap. These commands point you at the real cause before you waste an hour on the wrong one.

docker stats — Live Resource Use

docker stats streams a live table — per-container CPU percentage, memory usage against its limit, network I/O, and block I/O — updating about once a second. It is the fast way to see driftwood/web pinned at 100% CPU, or sitting at the edge of its --memory limit moments before an OOM kill. Run it on a single container to watch one closely:

docker stats web

The output refreshes in place, so you watch the numbers move rather than reading a snapshot. A container climbing steadily is telling you something the first line alone would not.

Reading Memory Against the Limit

The memory column shows usage and the cgroup limit side by side — 480MiB / 512MiB. A container creeping toward its limit is about to be OOM-killed by the kernel (Chapter 1, topic 03), and stats makes that approach visible before it happens rather than after. If the number is parked just under the cap and the container periodically dies, you have found the cause without reading a line of application code: the memory limit is too low for the workload, or the workload leaks.

docker events — The Daemon Event Stream

docker events prints a live feed of daemon-level activity: container start, die (with its exit code), oom, kill, health_status changes, image pulls, volume mounts. Watching it while a container crash-loops shows the exact die→start cycle and the exit code each time. Because it is a live stream, a past event is gone unless you ask for a window:

docker events --since 30m --until now \
  --filter container=web

--since and --until turn the stream into a query over history, which is how you recover the die that already happened. Without them, events shows only what occurs from the moment you run it forward.

docker inspect — Full Runtime State

docker inspect returns a container's complete config and live state as JSON: .State.Status, .State.ExitCode, .State.OOMKilled, .State.Health, .State.RestartCount, plus its mounts, networks, and environment. Reading the whole blob is rarely what you want; --format with a Go template pulls out the one or two fields that settle the question:

docker inspect \
  --format '{{.State.OOMKilled}} {{.State.ExitCode}} {{.State.RestartCount}}' \
  web

That one line tells you whether the kernel killed it, what code it exited with, and how many times it has restarted — the difference between "the app threw an exception" and "the kernel reaped it for exceeding its limit."

docker top — Processes Inside a Container

docker top web lists the processes running inside a container, using the host's ps against the container's namespace. It confirms whether PID 1 is the expected gunicorn and not a stray shell, and whether a zombie or an unexpected child process has appeared. It is a direct view of the fact that a container is just host processes (Chapter 1, topic 03), mapped through the container's PID namespace so you never mis-attribute a process to the wrong container the way filtering the host's ps by guesswork would.

Spotting OOM and Restart Loops

The four tools converge on one diagnosis. docker ps shows a high restart count or a Restarting status. inspect reports OOMKilled: true or a non-zero ExitCode. events shows the repeating oom→die→start cycle with the exit code each time. And stats confirms memory pressure by showing usage pinned at the cgroup limit. Four views, one cause — and once you have seen them line up, an OOM kill stops looking like a mysterious crash and becomes a memory-limit configuration you can fix.