Docker CPU Throttling: Why a Quiet VM Can Have a Slow Container
A Docker worker can hit its CPU quota while the VM has headroom. Compare limits, cgroup counter changes and job results before adding vCPUs.
DM
Imagine an export worker crawling through a batch while its four-vCPU VM looks only moderately busy. The first impulse is to buy more vCPUs. But the worker runs in a Docker container with its own CPU budget. The VM can have capacity that this container isn't allowed to use.
Before resizing, compare the container's CPU limit with throttling during the slow workload. A larger VM does not automatically change a container's configured quota. This is a hypothetical diagnostic walkthrough, not a report of a Krova incident or a benchmark.
Find the budget the worker actually received
Docker's resource constraints guide distinguishes --cpus, quota/period settings, CPU affinity and CPU shares. A bandwidth ceiling, a set of eligible CPUs and a relative scheduling weight are different controls. Raising shares is not the same change as raising a hard quota.
On the Linux machine running Docker, inspect the affected container. For a Cube workload, that means the Linux guest you operate—not Krova's physical host. Use an account already authorized to access Docker, and check that your Docker context targets the intended machine.
docker info --format 'cgroup={{.CgroupVersion}} driver={{.CgroupDriver}}'
docker inspect --type container --format \
'id={{.Id}} nano_cpus={{.HostConfig.NanoCpus}} quota={{.HostConfig.CpuQuota}} period={{.HostConfig.CpuPeriod}} cpuset={{.HostConfig.CpusetCpus}}' \
workerReplace worker with the real container. docker inspect supports selecting fields with a Go template. Keep the container ID with the deployment version so a replacement using the same name doesn't become an accidental before-and-after comparison. These fields describe configuration; inspect enforcement as well.
Read the container's cgroup, not the guest total
This walkthrough uses cgroup v2. Docker's runtime metrics guide describes finding the container's directory. Paths vary with the cgroup driver and runtime setup. Confirm the directory for that exact container on its Docker host; do not substitute the root cgroup or guess from a short ID. Rootless or delegated setups can add another hierarchy boundary.
After identifying that directory, set cg to its verified absolute path. The path below is deliberately an input to replace, not a universal Docker location. Capture the following at the beginning and end of the same representative workload interval.
cg=/absolute/path/to/the/verified/container/cgroup
TZ=Asia/Kolkata date -Is
cat "$cg/cpu.max"
cat "$cg/cpu.stat"The kernel's cgroup v2 interface defines cpu.max as a maximum and period, in microseconds. An illustrative value of 100000 100000 supplies a CPU-time budget equivalent to one CPU over the period. It does not promise a dedicated core. max means no bandwidth limit at that cgroup, not unlimited physical capacity.
The CPU bandwidth documentation explains how runnable threads share the group's budget and can be throttled when it runs out. A parallel worker can therefore reach its ceiling even while the broader VM has spare capacity. Look at the group's behavior during the export, not only a whole-VM average after it finishes.
Check ancestor limits too. Current kernel documentation explicitly distinguishes the cgroup's own bandwidth statistics from inherited throttling. A parent can constrain progress even when the child has budget remaining. If an ancestor is outside your visibility, record that limit in the diagnosis; don't treat missing visibility or missing controller fields as zero throttling.
Subtract snapshots before interpreting the counter
cpu.stat exposes bandwidth counters including nr_periods, nr_throttled and throttled_usec when the controller is enabled. Their accumulated values are not a measurement of just the current slow batch. Retain both snapshots, timestamps and container identity. If the cgroup was recreated or counters reset, start a new interval.
Here is invented arithmetic to show the distinction, not output collected from a server:
| Counter | Before | After | Change |
|---|---|---|---|
| nr_periods | 1,000 | 1,100 | 100 |
| nr_throttled | 200 | 260 | 60 |
The ratio of changes is 60 / 100 = 60%. It describes throttling occurrences relative to reported enforcement periods for this interval. It does not mean requests were 60% slower or that 60% of the VM's CPU was unavailable. A counter is evidence of an enforced boundary; application timing tells you whether that boundary matters to the job.
Likewise, don't label throttled_usec as a percentage of user-visible delay by dividing it blindly by elapsed wall time. Keep its scope and units alongside the raw change. Record export duration, completed items, errors and concurrent work over the same interval.
Choose a comparison that can change the decision
For the hypothetical export, the next useful step depends on what those observations show.
| Observation | Next comparison |
|---|---|
| Throttling grows during the slow phase and the guest has headroom | Rehearse a reviewed quota change or lower worker concurrency, one change at a time. |
| A parent budget is the constraint | Investigate that boundary before changing only the container's local limit. |
| CPU capacity is busy across the guest | Compare scheduling, concurrency and guest sizing using the same workload. |
| Little relevant throttling, but the job is slow | Investigate database waits, storage, network or application behavior before buying CPU. |
Keep input size, application version and concurrent jobs comparable. Write down the previous configuration and the conditions that would end the trial. A more generous quota can move pressure into a database, another container or memory; removing limits everywhere is not a controlled experiment. Verify useful output as well as completion time.
Memory is a separate sizing question. The Linux VM memory guide covers representative headroom observations. If the worker exits rather than merely slows down, the Docker exit 137 guide explains why an exit code alone doesn't identify the cause.
Start with one slow batch: preserve its container identity, configuration, two cgroup snapshots and application outcome. That gives you a concrete reason to adjust a limit, change concurrency or evaluate a larger guest—and something to compare after the change.
Rehearse the worker on a Cube
Use a self-managed Linux Cube for a representative staging workload. You operate Docker, resource limits and monitoring; choose capacity from verified job results.
Creation context: AI-assisted guidance based on the linked primary documentation, checked on 16 November 2026. The export scenario, counter values and proposed comparisons are illustrative and were not executed. No personal testing by the bylined author is claimed. The cover is an AI-generated conceptual illustration.




