Why Sentinel Misses Docker CPU Usage and How to Fix It

Sentinel Overview

In microservice governance, rate limiting, circuit breaking, and fallback are crucial. Open‑source options are limited; Guava for simple cases, Hystrix or Sentinel for complex ones. Sentinel, an Alibaba open‑source product, can be used at large scale with minimal custom development. Its main advantages are:

Lightweight with negligible performance overhead; only noticeable at >10k QPS on a single machine.

Out‑of‑the‑box console for dynamic configuration of rate‑limit and downgrade rules; persistence requires custom plugins.

Supports standalone and cluster rate limiting; non‑intrusive integration with frameworks such as Dubbo, gRPC, Spring MVC, reactive gateways, and even Envoy.

Rich rule set: limit by QPS, thread count, hot‑parameter, or system‑adaptive; circuit‑break rules based on response time, exception count or ratio.

Docker CPU Utilization Bug in Sentinel

Sentinel’s built‑in system‑adaptive rate limiting relies on CPU load and CPU utilization obtained via OperatingSystemMXBean. In Docker containers these methods return host‑level metrics, causing inaccurate limits. An issue was filed and initially answered with “use JDK 10”, which is not always feasible.

Eventually a code fix was contributed (see image). The fix correctly reads container‑specific CPU metrics.

Understanding System Load and CPU Utilization

CPU utilization is the CPU time used by a process divided by its total run time, normalized by the number of CPU cores. CPU load (load average) represents the number of running plus waiting processes. Both metrics are needed: when utilization is 100 % the load indicates which system is under heavier pressure.

Sentinel calculates a “instant” CPU utilization by measuring the JVM’s CPU time delta and the JVM’s elapsed time delta, then dividing by the core count. This provides a more precise snapshot than a historical average.

Three limitations exist:

Accurate container‑specific core count is only available from JDK 8u191 onward; earlier versions report host cores.

The code only measures the current Java process, not the whole container, which is acceptable for typical single‑process containers.

The final utilization picks the larger of host‑level and process‑level values; when Docker limits or isolates CPU, the two can diverge significantly, making host metrics less relevant.