Understanding the 'docker stats' Command (with examples)

The docker stats command is a powerful tool for monitoring Docker containers. It provides real-time streaming of various resource usage statistics for containers, helping developers and system administrators ensure optimal performance and resource allocation. From monitoring CPU usage to keeping an eye on memory consumption across different containers, docker stats delivers insights needed to maintain efficient Docker operations.

Use case 1: Display a live stream of statistics for all running containers

Code:

docker stats

Motivation:

Monitoring all running containers simultaneously is crucial for understanding the overall performance and health of your Docker environment. This command allows administrators to view real-time data, such as CPU and memory usage, for every active container, enabling quick identification of resource-intensive containers that may need optimization or further investigation.

Explanation:

• docker stats: This command, without additional arguments, initiates a live stream of resource usage metrics across all currently running containers. It provides a continuous feed of essential statistics that aid in monitoring containerized applications.

Example output:

CONTAINER ID   NAME           CPU %     MEM USAGE / LIMIT     MEM %     NET I/O            BLOCK I/O           PIDS
8a2bf53d12c1   web_app        5.23%     300MiB / 2GiB         14.65%    10MB / 20MB        500kB / 1MB         20
9f1dbb6c34a5   db_server      23.89%    1.2GiB / 4GiB         30.00%    30MB / 10MB        2MB / 3MB           50

Use case 2: Display a live stream of statistics for one or more specific containers

Code:

docker stats container1 container2

Motivation:

Focusing on specific containers is useful when troubleshooting specific applications or services. By narrowing the scope to select containers, users can analyze detailed performance metrics without distractions from other running containers. This precise insight is particularly beneficial during application testing, debugging, or when optimizing for resource efficiency.

Explanation:

• docker stats: Manages the monitoring stream for selected containers.
• container1 container2: Names (or IDs) of the containers to monitor. Specifying these limits the output to only the containers of interest, making it easier to focus on pertinent data.

Example output:

CONTAINER ID   NAME          CPU %     MEM USAGE / LIMIT     MEM %     NET I/O            BLOCK I/O           PIDS
8a2bf53d12c1   web_app       8.54%     350MiB / 2GiB         17.12%    15MB / 25MB        700kB / 1.5MB       22

Use case 3: Change the columns format to display container’s CPU usage percentage

Code:

docker stats --format ".Name:\t.CPUPerc"

Motivation:

Customizing the display format of docker stats allows users to concentrate on specific metrics tailored to their needs. When CPU utilization is of particular concern, this command strips out extraneous information, enhancing readability and focus, which is critical for performance tuning and reducing overhead.

Explanation:

• --format: This flag allows for the adjustment of the output layout. It supports Go template syntax to define which data points are shown.
• ".Name:\t.CPUPerc": Specifies the columns to be displayed. .Name refers to the container’s name, and .CPUPerc denotes the CPU percentage used by the container. The output is formatted to show these in a tab-separated format for clarity.

Example output:

web_app:	  7.23%
db_server:	  29.18%

Use case 4: Display statistics for all containers (both running and stopped)

Code:

docker stats --all

Motivation:

This option is particularly useful for retrospective analyses and troubleshooting, where understanding the resource usage patterns of both running and previously stopped containers is necessary. It aids in identifying historical spikes or trends in resource consumption, crucial for capacity planning and resource allocation.

Explanation:

• --all: This flag expands the scope of docker stats to include all containers, irrespective of their running state. It is used for comprehensive analyses that require historical data alongside real-time statistics.

Example output:

CONTAINER ID   NAME         CPU %     MEM USAGE / LIMIT     MEM %     NET I/O            BLOCK I/O           PIDS
8a2bf53d12c1   web_app      6.78%     290MiB / 2GiB         13.81%    5MB / 10MB         400kB / 800kB       19
3b2adf46a4f9   old_backup   0.00%     100MiB / 2GiB         5.00%     500kB / 500kB      200kB / 100kB       0

Use case 5: Disable streaming stats and only pull the current stats

Code:

docker stats --no-stream

Motivation:

Acquiring a single point-in-time snapshot of container resource usage can be enough for certain audits or reports. It minimizes the load on the Docker daemon and reduces noise when only current usage metrics are required, such as at the moment of a request or system check.

Explanation:

• --no-stream: This flag commands docker stats to collect and return metrics only once, rather than continuously streaming them. It offers a quick snapshot instead of ongoing monitoring, simplifying the output for immediate consumption.

Example output:

CONTAINER ID   NAME         CPU %     MEM USAGE / LIMIT     MEM %     NET I/O            BLOCK I/O           PIDS
8a2bf53d12c1   web_app      5.14%     280MiB / 2GiB         13.52%    8MB / 16MB         300kB / 900kB       21

Conclusion:

The docker stats command is an indispensable utility for Docker container management, offering a detailed overview of resource consumption. By tailoring its functionality with various options, users can extract the precise data needed, whether for real-time monitoring, targeted analysis, or instant snapshots. This versatility makes it a critical tool in maintaining efficient, scalable, and well-optimized container ecosystems.