docker-stats

Display a live stream for the statistics of all running containers

$ docker stats

$ docker stats [container1 container2 ...]

$ docker stats --format "[.Name]:\t[.CPUPerc]"

$ docker stats [[-a|--all]]

$ docker stats --no-stream

docker stats [OPTIONS] [CONTAINER...]

This command is a subcommand of the main docker CLI. It accepts various OPTIONS to modify its behavior and can target specific CONTAINER names or IDs. If no containers are specified, it defaults to showing statistics for all running containers.

-a, --all
    Show all containers (default shows only running containers).

--no-stream
    Disable streaming stats and only pull the first result, providing a single snapshot of resource usage.

--format string
    Pretty-print stats using a Go template. For example, --format "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}".

--no-trunc
    Do not truncate output. Useful for displaying full container IDs or names.

The docker stats command provides a live stream of resource usage statistics for one or more Docker containers. By default, it displays metrics for running containers, including CPU percentage, memory usage (with limit), network I/O (input/output), block I/O (disk reads/writes), and process IDs (PIDs). This command is invaluable for monitoring container performance, identifying resource bottlenecks, and debugging issues in a Dockerized environment. When invoked without specific container names or IDs, it shows statistics for all currently running containers. The stream continues until manually interrupted (e.g., Ctrl+C) or if the --no-stream option is used to capture a single snapshot. It offers quick, at-a-glance insights into your containerized applications' resource consumption.

docker stats relies on the Docker daemon for metrics, which means it requires the Docker daemon to be running and accessible. The CPU percentage shown can sometimes be misleading as it's calculated based on the host's total CPU cores, not necessarily the container's allocated shares or limits. Memory usage represents the total memory consumed by the container, which includes filesystem cache and other kernel-level allocations, not just application-specific memory. For very high-resolution or historical data, other tools like Prometheus and Grafana, integrated with Docker, might be more suitable. There can be a slight overhead involved in collecting and streaming these statistics, especially with a large number of containers.

The default output of docker stats includes several columns:

• CONTAINER ID: The unique ID of the container.
• NAME: The name of the container.
• CPU %: The current CPU usage percentage of the container.
• MEM USAGE / LIMIT: Current memory usage and the total memory limit for the container.
• NET I/O: Network input/output, showing bytes sent and received.
• BLOCK I/O: Block input/output, showing bytes read from and written to block devices.
• PIDS: The number of processes currently running inside the container.

The --format option allows for highly customizable output using Go templates. This is particularly useful for scripting or integrating docker stats output into other tools. Available placeholders include .ID, .Name, .CPUPerc, .MemUsage, .MemLimit, .MemPerc, .NetIO, .BlockIO, .PIDs. For example, to get just the container ID and CPU percentage in a table format: docker stats --format "table {{.ID}}\t{{.Name}}\t{{.CPUPerc}}".

The docker stats command was introduced relatively early in Docker's development lifecycle, becoming a staple for users needing immediate insight into container resource consumption. Its inclusion underscored Docker's commitment to providing robust monitoring capabilities directly within its command-line interface. Over time, features like the --format option were added to enhance its utility, allowing users to customize output for scripting and integration purposes. It has consistently remained a core component of the docker CLI, evolving with the Docker engine itself to provide more accurate and comprehensive metrics.

docker ps(1), docker top(1), docker inspect(1), docker logs(1), top(1), htop(1), free(1), iostat(1)