Docker Stats: Real-time Container Monitoring

1. Basic Real-Time Monitoring

The simplest way to start is by running the command without any arguments. This gives you a live-streaming dashboard of all running containers.

docker stats

Let's watch a short video that introduces the command and its basic options.

The output you see will look something like this, showing key performance indicators for each container.

2. Understanding the Metrics

The default docker stats output provides a wealth of information. To use it effectively, you need to know what each column represents. Let's break them down.

Here's a summary of the key points from the reading:

• CONTAINER ID and NAME: Identifiers for the container.
• CPU %: The percentage of the host's total CPU capacity that the container is using. On a multi-core system, this value can exceed 100%. For example, 250% usage on an 8-core machine means the container is using 2.5 full CPU cores.
• MEM USAGE / LIMIT: The amount of memory the container is currently using, versus the total memory it's allowed to use. If no limit is set, the limit will be the host's total memory.
• MEM %: The container's memory usage as a percentage of its limit.
• NET I/O: The total amount of data received and transmitted by the container over its network interfaces.
• BLOCK I/O: The total amount of data read from and written to the host's block devices (i.e., disk I/O) by the container.
• PIDS: The number of processes running inside the container. A high number in a simple application could indicate a problem like a process leak.

3. Advanced Usage and Custom Formatting

While the default view is useful for a quick glance, in a professional DevOps context, you'll often need to script, automate, or integrate this data. This is where docker stats becomes particularly powerful.

You can customize the output using the --format flag, which uses Go template syntax. This allows you to select specific fields, format them, and even output them as JSON for easy parsing by other tools.

Practical Examples for Automation

1. Get a single snapshot of specific metrics in a table:
   The --no-stream flag is essential for scripting, as it provides a one-time output instead of a continuous stream.

   # Show container name, CPU %, and Memory Usage in a clean table
   docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"
   

2. Output as JSON for scripting:
   This is incredibly useful for feeding data into monitoring systems or scripts.

   # Get a JSON object for each running container
   docker stats --no-stream --format "{{json .}}"
   

   This will produce a raw stream of JSON objects, one per container.

3. Combine with jq to find problematic containers:
   Given your DevOps background, you'll appreciate how easily this integrates with command-line tools like jq.

   # Find all containers using more than 50% of their memory limit
   # The jq script filters the JSON objects based on the MemPerc field
   docker stats --no-stream --format "{{json .}}" | jq 'select((.MemPerc | rtrimstr("%") | tonumber) > 50)'
   

docker stats --no-stream --format "{{.Name}},{{.CPUPerc}},{{.MemPerc}}"

4. Under the Hood: How It Works

docker stats isn't magic. It's a user-friendly frontend for metrics collected by the Linux kernel itself. Your background in Linux and Computer Science makes this an interesting area to explore.

Docker leverages a kernel feature called Control Groups (cgroups). Cgroups are responsible for isolating resources (CPU, memory, block I/O) for a collection of processes. As a side effect of managing these resources, the kernel exposes detailed metrics about them in a pseudo-filesystem, typically located at /sys/fs/cgroup.

In essence, when you run docker stats, the Docker daemon is reading files from directories like /sys/fs/cgroup/memory/docker/<container-id>/ and /sys/fs/cgroup/cpuacct/docker/<container-id>/, parsing the raw data, and presenting it in a human-readable format. This is why the command has very little performance overhead—it's just reading statistics that the kernel is already collecting.

Conclusion

In this lesson, you've learned how to use docker stats as a powerful tool for real-time monitoring of your containers. This moves your skills from managing static images to observing live, running applications—a critical competency for any DevOps role.

Key Takeaways:

• docker stats provides a live, top-like view of resource usage for all running containers.
• The metrics include CPU, memory, network I/O, block I/O, and process counts, each with specific meanings.
• The --format flag is extremely powerful for automation, allowing you to create custom-formatted output, including JSON for easy parsing with tools like jq.
• The underlying mechanism for this monitoring is the Linux kernel's cgroups feature, which collects resource metrics with minimal overhead.

In our next lesson, we will build on this by looking at how to manage the container lifecycle. You will learn to manage the container lifecycle (stop, restart, remove) and configure restart policies for automatic recovery, ensuring your applications can gracefully handle failures.