Introduction

High Docker memory usage usually comes from application behavior, memory limits, and how the host reports cached pages. Containers are not virtual machines, so memory accounting can feel confusing at first. This guide explains how to measure actual usage, apply limits safely, and troubleshoot common leaks.

Understand Container Memory Metrics

Different tools show different numbers. docker stats reports current usage and limits, while host tools may include cache and shared memory differently.

docker stats

docker inspect <container_id> --format '{{json .HostConfig.Memory}}'

If memory limit is zero in inspect output, the container can consume host memory without a cgroup cap.

Set Explicit Memory Limits

Apply limits at run time to prevent one container from exhausting the host.

1docker run \
2  --name api \
3  --memory=512m \
4  --memory-swap=512m \
5  my-api-image

For Docker Compose:

1services:
2  api:
3    image: my-api-image
4    mem_limit: 512m

Set realistic limits based on profiling, not guesswork. Limits that are too low can cause frequent out-of-memory kills.

Diagnose Growth Over Time

If usage climbs continuously, profile the process inside the container.

docker exec -it <container_id> sh
ps aux
cat /proc/meminfo

Language-specific profilers are often required for leak analysis:

• Python with tracemalloc or objgraph.
• Node.js with heap snapshots.
• Java with heap dump tools.

Container metrics tell you that growth exists, but runtime profilers explain why.

Distinguish Cache from Real Leak

Linux page cache may make memory appear high even when the app heap is stable. Track resident set size and runtime heap metrics rather than only host-level memory views.

If request volume spikes, short-lived cache growth can be normal. Confirm whether memory drops after traffic subsides before assuming a leak.

Use Alerts and Baselines

Set observability baselines for normal usage per service. Alert on sustained growth slope, not single spikes.

Example policy:

• Warning when memory exceeds eighty percent of limit for ten minutes.
• Critical when repeated out-of-memory restarts occur.

This reduces noisy alerts and focuses attention on real degradation patterns.

Track Memory with Prometheus and cAdvisor

For long-term analysis, collect container memory metrics and correlate with deploys, traffic, and garbage collection events.

container_memory_working_set_bytes{container!="", image!=""}

Useful companion queries:

rate(container_oom_events_total[5m])
container_memory_rss{container!="", image!=""}

Working set is often a better operational signal than raw usage because it approximates active memory pressure. Combine these metrics with application-level heap metrics to distinguish host cache behavior from true process growth.

Practical Remediation Checklist

When you observe unexplained memory growth, follow a fixed checklist:

1. Confirm container memory limit exists.
2. Check restart history for out-of-memory kills.
3. Compare heap versus resident set metrics.
4. Capture heap profile during growth window.
5. Validate request or queue backlog growth.

A structured workflow prevents random tuning and makes incident response repeatable across teams.

Capacity Planning Habit

Track per-service memory percentiles by release version. This creates a baseline that helps identify regressions quickly after deployment and supports more accurate limit tuning over time.

Common Pitfalls

A common pitfall is launching containers without memory limits and later blaming Docker itself for high consumption.

Another issue is interpreting cache growth as application leak without checking runtime heap metrics.

Developers also set memory limits too aggressively, causing unstable restart loops.

A final mistake is profiling only host memory and skipping in-process diagnostics where root cause usually lives.

Summary

• Use container-aware metrics to understand memory usage correctly.
• Set explicit memory limits and tune them using real workload data.
• Profile application heap when memory grows persistently.
• Differentiate page cache behavior from true leaks.
• Alert on sustained patterns and restart behavior, not single spikes.