From 171569f8ee6724a4113a0100fea6ff83d9b70c6a Mon Sep 17 00:00:00 2001 From: Sun Shaojie Date: Mon, 29 Jun 2026 14:06:36 +0800 Subject: [PATCH] cgroup/cpu: document cpu.stat.local and clarify cpu.stat behavior MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for the cpu.stat.local interface file, which reports the throttled_usec stat -- the actual throttling time incurred by the cgroup's own runqueues, which may include throttling inherited from ancestor cgroup bandwidth limits. Unlike cpu.stat's throttled_usec which only accounts for throttling caused by the cgroup's own CFS bandwidth limit. When the controller is not enabled, the stat is not reported. Also clarify cpu.stat descriptions: note that the three base CPU usage stats (usage_usec, user_usec, system_usec) include descendant cgroups, and that the five CFS bandwidth stats are non-hierarchical -- they only account for throttling caused by the cgroup's own bandwidth limit. Signed-off-by: Sun Shaojie Acked-by: Michal Koutný Signed-off-by: Tejun Heo --- Documentation/admin-guide/cgroup-v2.rst | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 1bf219829465..851a1cf1bc22 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1145,7 +1145,7 @@ will be referred to. All time durations are in microseconds. This file exists whether the controller is enabled or not. It always reports the following three stats, which account for all the - processes in the cgroup: + processes in the cgroup (including those in descendant cgroups): - usage_usec - user_usec @@ -1160,6 +1160,27 @@ will be referred to. All time durations are in microseconds. - nr_bursts - burst_usec + Note that the above five CFS bandwidth stats are non-hierarchical; + they only account for throttling caused by this cgroup's own bandwidth + limit, not including throttling inherited from ancestor cgroups. + + cpu.stat.local + A read-only flat-keyed file. + This file exists whether the controller is enabled or not. + + It reports the following stat when the controller is enabled: + + - throttled_usec + + Unlike the ``throttled_usec`` reported by ``cpu.stat`` which + accounts for throttling caused by this cgroup's own CFS + bandwidth limit, ``cpu.stat.local`` reports the actual + throttling time incurred by this cgroup's own runqueues, + which may include throttling inherited from ancestor + cgroup bandwidth limits. + + When the controller is not enabled, this stat is not reported. + cpu.weight A read-write single value file which exists on non-root cgroups. The default is "100".