DockerContainerCpuThrottled: what to do when it fires

Alert rule

alert: DockerContainerCpuThrottled
expr: rate(container_cpu_cfs_throttled_periods_total{name!=""}[5m])
  / rate(container_cpu_cfs_periods_total{name!=""}[5m]) * 100 > 25
for: 15m
severity: warning

Alert message: CPU throttling of container {{ $labels.name }} ({{ $labels.instance }})

What it means

The container is hitting its CPU limit: more than 25% of CFS scheduler periods were throttled over 15 minutes. The application slows down even though the host may have free CPU.

Common causes

A --cpus / cpu_quota / deploy.resources.limits.cpus value that is too low, increased load, a multithreaded application for which a fractional limit is too small.

Diagnostics

docker stats --no-stream <name>
docker inspect <name> --format 'CPUs={{.HostConfig.NanoCpus}} quota={{.HostConfig.CpuQuota}} period={{.HostConfig.CpuPeriod}}'
docker top <name>

NanoCpus is in billionths of a core (1000000000 is one core); 0 means no limit.

How to fix

Raise the CPU limit, or optimise the application, or add replicas. If the limit exists only "for the sake of order", consider removing it and using cpu_shares.

When it is OK to silence

For background containers that are not hurt by throttling (low-priority jobs).

Related alerts

• DockerContainerMemoryNearLimit
• DockerContainerRestartLoop
• DockerContainerOomKilled
• DockerContainerGone
• DockerCadvisorDown

The full pack of 44 tested rules + Alertmanager → Telegram: 790 ₽ (≈ $9, card payment in rubles)
Open in Telegram · Free Monitoring Lite kit · All runbook alerts