15.2.2.1 Stats Live Display

The stats live display is the continuously refreshing terminal view docker stats produces by default, redrawing the screen on each update cycle similar to tools like top, and understanding its specific refresh and rendering behavior clarifies both why it behaves differently from a simple repeated command and how to use it effectively during an active, real-time investigation.

How the refresh cycle works

Unlike running a command in a loop with watch, docker stats maintains a persistent connection to the daemon's statistics stream and redraws its display in place each time new data arrives, rather than clearing and re-running the entire command from scratch on each cycle:

docker stats

This persistent connection means the live display reflects genuinely continuous data from the daemon, rather than a series of independent snapshots each incurring their own connection and query overhead, which is part of why the live display feels more responsive than wrapping a --no-stream invocation in an external polling loop.

Containers starting and stopping during a live session

The live display automatically adds newly started containers to its output and removes stopped ones, without needing to restart the command, which makes it suitable for watching resource usage through a deployment or scaling event as containers come and go:

docker stats
# in another terminal:
docker run -d --name my-new-worker my-worker:1.0

The new container appears in the running docker stats display automatically, with no interruption to the existing output, which is a meaningful difference from a script that captured a fixed list of container names at startup and would not pick up new containers without being restarted.

Terminal rendering and screen size considerations

Because the live display redraws in place, it is sensitive to terminal width when many containers are running simultaneously, often truncating columns or wrapping awkwardly in a narrow terminal, which is worth widening the terminal window to avoid before starting an extended monitoring session involving many containers:

docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemPerc}}"

Using a custom, narrower format with --format is a practical way to keep the live display readable in a constrained terminal width, rather than fighting with the default, wider table layout truncating in unpredictable ways.

Running inside tmux or screen for persistent monitoring

Because the live display runs as a long-lived, foreground terminal process, running it inside a terminal multiplexer like tmux or screen allows it to keep running in the background of a session and be reattached to later, which is convenient for leaving a live monitoring view running throughout an extended investigation or deployment window:

tmux new-session -d -s monitoring 'docker stats'
tmux attach -t monitoring

This pattern is particularly useful during a deployment that an operator wants to watch end to end without keeping a dedicated terminal window open and actively focused the entire time.

Comparison to top-like alternative tools

Several third-party tools provide a more feature-rich, interactive live display than docker stats itself, generally adding the ability to sort by a specific column, drill into a container's logs or shell directly from the same interface, or visualize trends rather than just current values:

docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock lazyteam/lazydocker

docker run --rm -ti --name=ctop -v /var/run/docker.sock:/var/run/docker.sock quay.io/vektorlab/ctop:latest

Tools like ctop and lazydocker are essentially enhanced, interactive replacements for the basic docker stats live display, adding sorting, container actions, and sometimes simple historical sparkline graphs directly in the terminal, which is useful for an operator who spends significant time doing interactive container investigation and wants more than the bare live display provides.

Exiting the live display cleanly

The live display runs until interrupted, typically with Ctrl+C, which terminates the docker stats process itself without affecting any of the containers being monitored:

docker stats
# Ctrl+C to exit

This is a purely client-side monitoring connection; closing it has no effect whatsoever on the containers it was displaying, which is worth knowing explicitly, since it removes any hesitation about leaving a stats session running or stopping one abruptly during an investigation.

Limitations of the live display for extended observation

The live display shows only current values, with no built-in way to see a trend or compare the current reading against a value from a few minutes earlier within the display itself; an operator relying on visual memory of "it was lower a moment ago" is working with a much less reliable signal than an actual time-series graph would provide:

docker stats

For any investigation requiring an actual historical comparison, exporting the same underlying metrics to a persistent system and viewing them as a graph is considerably more reliable than attempting to track a trend by eye against a continuously updating terminal display.

Common mistakes

• Running the live display in a terminal too narrow to show all relevant columns clearly, missing data due to truncation rather than realizing a custom, narrower format would resolve it.
• Assuming the live display retains any history once closed, when in fact it shows only the current moment with no memory of prior readings.
• Not using a terminal multiplexer for an extended monitoring session, losing the live view entirely if the terminal connection drops.
• Trying to visually track a resource trend by eye across many container restarts of the display, rather than exporting metrics to a system actually designed for trend visualization.
• Overlooking more feature-rich alternative tools like ctop or lazydocker when extensive day-to-day interactive container investigation would benefit from their additional sorting and drill-down capabilities.

The stats live display is a genuinely useful, zero-setup tool for real-time, interactive container observation, especially when run inside a persistent terminal session, but its lack of any historical memory means it should be treated as a complement to, rather than a substitute for, an actual metrics pipeline for anything beyond a single, current-moment investigation.