Container resource usage stats in Docker - Deep Dive

Overview - Container resource usage stats

What is it?

Container resource usage stats show how much CPU, memory, network, and disk a running container uses. These stats help you understand the container's performance and resource needs. You can see if a container is using too much or too little of your system's resources. This information is important for managing containers efficiently.

Why it matters

Without resource usage stats, you might not know if a container is slowing down your system or causing problems. This can lead to crashes, slow applications, or wasted resources. Knowing resource usage helps you fix issues early, optimize performance, and save costs by not overusing hardware.

Where it fits

Before learning container stats, you should understand basic Docker concepts like containers and images. After this, you can learn about container orchestration and scaling, which rely on resource monitoring to work well.

Mental Model

Core Idea

Container resource usage stats are like a health check that tells you how much of your computer's power each container is using right now.

Think of it like...

Imagine each container is a car on a highway, and resource stats are the speedometer and fuel gauge showing how fast the car is going and how much fuel it uses.

┌───────────────────────────────┐
│       Container Stats          │
├─────────────┬───────────────┤
│ CPU Usage   │ Memory Usage   │
├─────────────┼───────────────┤
│ Network I/O │ Disk I/O      │
└─────────────┴───────────────┘

Build-Up - 7 Steps

1

Foundation

What are container resource stats

Concept: Introduce the basic idea of resource stats for containers.

Containers run applications isolated from the rest of the system. Each container uses some CPU, memory, network, and disk. Resource stats measure these amounts so you can see how busy or idle a container is.

Result

You understand that resource stats are measurements of container activity and resource use.

Understanding resource stats is the first step to managing container performance and health.

2

Foundation

Using docker stats command

Concept: Learn the basic command to see live resource stats of containers.

Run the command: docker stats This shows a live table of CPU %, memory %, network I/O, and block I/O for all running containers. Each row is one container.

Result

You see a live updating list of resource usage for your containers.

Knowing the docker stats command lets you quickly check container health without extra tools.

3

Intermediate

Interpreting CPU and memory usage

🤔Before reading on: do you think a high CPU % always means a problem? Commit to your answer.

Concept: Understand what CPU % and memory usage numbers mean in context.

CPU % shows how much processor time a container uses. High CPU means the container is busy. Memory usage shows how much RAM the container uses. High memory can cause slowdowns or crashes if it exceeds limits.

Result

You can tell if a container is working hard or using too much memory.

Knowing what CPU and memory stats mean helps you spot performance bottlenecks or leaks.

4

Intermediate

Network and disk I/O stats explained

🤔Before reading on: do you think network I/O stats show total data sent or current speed? Commit to your answer.

Concept: Learn what network and disk input/output stats represent for containers.

Network I/O shows total data sent and received by the container's network interfaces. Disk I/O shows data read and written to storage. These stats help identify if a container is waiting on slow network or disk operations.

Result

You understand how to check if containers are limited by network or disk speed.

Recognizing network and disk usage patterns helps diagnose slow container responses.

5

Intermediate

Filtering stats for specific containers

Concept: Learn how to view stats for one or a few containers instead of all.

Use docker stats with container names or IDs: docker stats container1 container2 This shows stats only for the specified containers, making it easier to focus on important ones.

Result

You can monitor resource usage of specific containers without clutter.

Filtering stats helps you focus on containers that matter most in your environment.

6

Advanced

Automating stats collection and alerts

🤔Before reading on: do you think docker stats can be used directly in scripts for alerts? Commit to your answer.

Concept: Explore how to collect stats data automatically and trigger alerts on problems.

Docker stats outputs live data that can be parsed by scripts or monitoring tools. You can write scripts to check if CPU or memory usage exceeds thresholds and send alerts. This helps catch issues before users notice.

Result

You can build automated monitoring and alerting based on container stats.

Automating stats monitoring turns manual checks into proactive system health management.

7

Expert

Limitations and internals of docker stats

🤔Before reading on: do you think docker stats shows historical data or only live usage? Commit to your answer.

Concept: Understand what docker stats can and cannot do, and how it gathers data internally.

Docker stats shows only live, current resource usage, not historical trends. It gathers data from the container runtime and cgroups in the Linux kernel. It does not store data long-term. For history, external monitoring tools are needed.

Result

You know the scope and limits of docker stats and when to use other tools.

Knowing docker stats' limits prevents relying on it for long-term analysis or detailed metrics.

Under the Hood

Docker stats collects resource usage data from Linux cgroups, which track CPU, memory, network, and disk usage per container. It queries these kernel features in real-time and formats the data for display. The data is live and reflects current container activity without storing history.

Why designed this way?

Docker stats was designed for quick, live monitoring without overhead of storing data. Using kernel cgroups ensures accurate resource tracking with minimal performance impact. Historical data storage was left to external tools to keep Docker lightweight.

┌─────────────┐
│ Docker CLI  │
└──────┬──────┘
       │ docker stats command
       ▼
┌─────────────┐
│ Docker Daemon│
└──────┬──────┘
       │ queries
       ▼
┌─────────────┐
│ Linux cgroups│
│ (resource   │
│ tracking)   │
└─────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does a high CPU % always mean a container is misbehaving? Commit yes or no.

Common Belief: High CPU usage means the container is broken or causing problems.

Reality: High CPU usage can mean the container is working hard as expected, not necessarily a problem.

Why it matters: Misinterpreting high CPU as bad can lead to unnecessary restarts or resource limits, hurting performance.

Quick: Does docker stats provide historical resource usage data? Commit yes or no.

Common Belief: Docker stats shows past resource usage over time.

Reality: Docker stats only shows live, current usage, not historical data.

Why it matters: Expecting history from docker stats can cause confusion and missed trends; external monitoring is needed.

Quick: Does network I/O in docker stats show current speed or total data transferred? Commit your answer.

Common Belief: Network I/O shows current network speed in bytes per second.

Reality: Network I/O shows total bytes sent and received since container start, not speed.

Why it matters: Misreading network I/O as speed can lead to wrong conclusions about network performance.

Quick: Can docker stats monitor containers that are stopped? Commit yes or no.

Common Belief: Docker stats can show resource usage for stopped containers.

Reality: Docker stats only works for running containers; stopped containers have no live stats.

Why it matters: Trying to monitor stopped containers wastes time and causes confusion.

Expert Zone

1

Docker stats relies on cgroups which may report CPU usage differently on various kernel versions, affecting precision.

2

Resource usage can spike briefly and docker stats refresh rate might miss short bursts, so sampling frequency matters.

3

Memory usage includes cache and buffers which may not indicate actual memory pressure, requiring deeper analysis.

When NOT to use

Docker stats is not suitable for long-term monitoring or detailed analytics. Use dedicated monitoring tools like Prometheus, Grafana, or cloud monitoring services for historical data and alerting.

Production Patterns

In production, docker stats is often integrated into monitoring pipelines via scripts or agents. Teams use it for quick health checks and debugging, while relying on full monitoring stacks for trends and capacity planning.

Connections

Linux cgroups

Docker stats builds on Linux cgroups to get resource data.

Understanding cgroups helps explain how container resource limits and stats work at the system level.

System monitoring tools

Docker stats complements system monitoring tools like top or htop.

Knowing system monitoring helps interpret container stats in the context of overall host health.

Human physiology

Both container stats and human vital signs measure real-time health indicators.

Recognizing this similarity helps appreciate the importance of continuous monitoring for early problem detection.

Common Pitfalls

#1 Trying to monitor stopped containers with docker stats.

Wrong approach:

docker stats container_name_stopped

Correct approach:

docker stats container_name_running

Root cause:

Misunderstanding that docker stats only works for running containers.

#2 Assuming network I/O shows current network speed.

Wrong approach:

Reading network I/O columns as bytes per second speed.

Correct approach:

Use external tools or calculate speed by sampling network I/O over time.

Root cause:

Confusing cumulative data counters with instantaneous rates.

#3 Using docker stats alone for long-term performance analysis.

Wrong approach:

Relying on docker stats output to track trends over days or weeks.

Correct approach:

Set up monitoring tools like Prometheus and Grafana for historical data and alerts.

Root cause:

Not knowing docker stats only shows live data without history.

Key Takeaways

Container resource usage stats provide a live snapshot of CPU, memory, network, and disk use for running containers.

The docker stats command is a simple way to see these stats in real-time for one or many containers.

Understanding what each stat means helps identify performance issues and resource bottlenecks.

Docker stats relies on Linux kernel features and does not store historical data, so external tools are needed for long-term monitoring.

Misinterpreting stats or expecting features docker stats does not have can lead to wrong decisions and wasted effort.