Resource Limits & OOM

## Two different ideas CPU controls in Docker come in two families that candidates constantly conflate: **proportional weight** (who wins when there is contention) and **hard bandwidth** (an absolute ceiling regardless of idle capacity). Getting that distinction right is the whole question. ## Weight: `--cpu-shares` `--cpu-shares` maps to the cgroup CPU weight (`cpu.shares` on v1, `cpu.weight` on v2). The default is 1024 and only the *ratio* matters: two containers at 1024 and 512, both runnable and competing for the same CPU, get roughly a 2:1 split. The critical property is that shares are meaningless when the CPU is not saturated. A container with 100 shares on an idle 16-core host can use all 16 cores. Shares are therefore a priority mechanism — never a guarantee, never an isolation boundary, never something you can bill against. They are the right tool when a batch job should yield to a latency-sensitive service without being capped when the box is quiet. ## Bandwidth: `--cpu-quota` and `--cpu-period` The Completely Fair Scheduler's bandwidth control gives each cgroup a budget of CPU time per interval. `--cpu-period=100000` (microseconds — the default 100 ms) with `--cpu-quota=50000` means: across all its threads, the container may consume 50 ms of CPU time in each 100 ms window, i.e. half a core. When the budget is spent, every runnable thread in the cgroup is de-scheduled until the next period begins. This is a genuine cap: it applies even on a completely idle host. `--cpus=0.5` is exactly this pair expressed once, and is the flag you should normally reach for; `--cpus=2` means quota 200000 per 100000 period — two cores' worth of time, spendable in parallel across many cores. ## Why quotas hurt latency The subtlety is that quota is consumed *in parallel*. A service with 20 threads under `--cpus=1` can burn its entire 100 ms budget in roughly 5 ms of wall-clock time if all threads run at once — and then the whole container is frozen for the remaining ~95 ms. Average CPU usage looks like a comfortable 1.0 while p99 latency contains ~95 ms of pure stall. This is the classic "my container is only at 40% CPU but requests are slow" report. Mitigations: raise the quota so bursts fit; reduce thread or worker counts so parallelism matches the quota; shorten the period (`--cpu-period=10000`) so stalls are smaller though more frequent; or drop the hard cap for latency-critical services and rely on weights plus capacity planning. ## Detecting throttling `docker stats` will not tell you. A throttled container simply reports usage at its ceiling and looks fine. The evidence lives in the cgroup: `cpu.stat` exposes `nr_periods`, `nr_throttled` and `throttled_usec` (on cgroup v1, `throttled_time`). A steadily climbing `nr_throttled` as a fraction of `nr_periods` — anything sustained above a few percent for a latency-sensitive service — means the cap is actively hurting. Read it via `docker exec` or from the host's cgroup tree. ## Pinning: `--cpuset-cpus` `--cpuset-cpus=0-3` restricts the container to those specific CPUs. This is neither proportional nor a time budget — it is placement. It helps with NUMA locality, cache warmth for pinned workloads, and keeping noisy neighbours off cores reserved for a critical service. It also implicitly caps parallelism at the number of assigned cores. ## Interaction with runtimes Language runtimes read the quota to size their internal parallelism. A JVM derives its active processor count from quota divided by period, which drives GC thread counts, JIT compiler threads, the common ForkJoinPool and any library calling `availableProcessors()`; recent Go runtimes behave similarly, while older versions read host core count and over-schedule. Setting `--cpus=0.5` therefore does not merely slow a runtime, it reconfigures it — typically down to a single reported "processor". ## Choosing A workable default: set `--cpus` on everything so no container can monopolise a host, size it above measured peak burst rather than average, and use shares only to express priority between co-located classes of work. Reserve `--cpuset-cpus` for genuinely latency-critical, NUMA-sensitive services. And whenever someone reports "slow but low CPU", check `cpu.stat` before anything else.