cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec
Subsystems (2)
PATCH 1/1 cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec
From: Tao Cui <[email protected]>
cgroup_base_stat_cputime_show() unconditionally prints a fourth base stat, nice_usec, in addition to usage_usec/user_usec/system_usec, and also prints core_sched.force_idle_usec when CONFIG_SCHED_CORE is enabled. Neither field is currently described in the cpu.stat section of cgroup-v2.rst, which still states it "always reports the following three stats".
nice_usec was added by commit aefa398d93d5 ("cgroup/rstat: Tracking cgroup-level niced CPU time") and core_sched.force_idle_usec by commit 1fcf54deb767 ("sched/core: add forced idle accounting for cgroups"); the documentation was not updated in either case.
Update the cpu.stat description to list both fields and fix the count.
--- Documentation/admin-guide/cgroup-v2.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-)
Documentation/admin-guide/cgroup-v2.rst +7 -1
@@ -1144,12 +1144,18 @@ will be referred to. All time durations are in microseconds. A read-only flat-keyed file. This file exists whether the controller is enabled or not. - It always reports the following three stats, which account for all the + It always reports the following four stats, which account for all the processes in the cgroup (including those in descendant cgroups): - usage_usec - user_usec - system_usec + - nice_usec + + When core scheduling (CONFIG_SCHED_CORE) is enabled, an additional + stat is reported: + + - core_sched.force_idle_usec and the following five when the controller is enabled, which account for only the processes under the fair-class scheduler:
Signature · 1 line
2.43.0
Quoted 9 lines
From: Tao Cui <[email protected]>
cgroup_base_stat_cputime_show()unconditionally prints a fourth base stat,nice_usec, in addition to usage_usec/user_usec/system_usec, and also prints core_sched.force_idle_usec whenCONFIG_SCHED_COREis enabled. Neither field is currently described in the cpu.stat section ofcgroup-v2.rst, which still states it "always reports the following three stats".
Quoted 8 lines
nice_usecwas added by commitaefa398d93d5("cgroup/rstat: Tracking cgroup-level niced CPU time") and core_sched.force_idle_usec by commit1fcf54deb767("sched/core: add forced idle accounting for cgroups"); the documentation was not updated in either case.Update the cpu.stat description to list both fields and fix the count.
Signed-off-by Tao Cui <[email protected]>
Hello Tao, thank you for the patch! I should have updated this when I added the nice stats. Thank you for finding this and updating it.
Quoted 9 lines
--- Documentation/admin-guide/cgroup-v2.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-)Documentation/admin-guide/cgroup-v2.rst +0
-0
Documentation/admin-guide/cgroup-v2.rst will be referred to. All time durations are in microseconds. · line 1148
Quoted 6 lines
Documentation/admin-guide/cgroup-v2.rst +1
-1@@ -1144,12 +1144,18 @@ will be referred to. All time durations are in microseconds. A read-only flat-keyed file. This file exists whether the controller is enabled or not. - It always reports the following three stats, which account for all the + It always reports the following four stats, which account for all the processes in the cgroup (including those in descendant cgroups):
I have to ask, which tree is this based on? I can't seem to find a single tree that contains the "(including those in descendant cgroups)" section anywhere.
Quoted 14 lines
Documentation/admin-guide/cgroup-v2.rst +6
-0- usage_usec - user_usec - system_usec + - nice_usec + + When core scheduling (CONFIG_SCHED_CORE) is enabled, an additional + stat is reported: + + - core_sched.force_idle_usec and the following five when the controller is enabled, which account for only the processes under the fair-class scheduler:Signature · 1 line
2.43.0
Otherwise, the change looks good. I just wanted to know what it was based on, in case I'm missing something. Thanks, have a great day! Joshua
Michal Koutný
maintainerQuoted 3 lines · Joshua Hahn
I have to ask, which tree is this based on? I can't seem to find a single tree that contains the "(including those in descendant cgroups)" section anywhere.
It is most likely linux-next which contains a nearby modification from
[1] (or it was based on that regardless).
HTH,
Michal
Joshua Hahn
Reviewed-byQuoted 7 lines · Joshua Hahn
Quoted 3 lines
I have to ask, which tree is this based on? I can't seem to find a single tree that contains the "(including those in descendant cgroups)" section anywhere.
It is most likely linux-next which contains a nearby modification from
[1] (or it was based on that regardless).
Hello Michal,
Thank you, I must have missed linux-next in my searching... that makes a lot of sense! With that, Tao, please feel free to add my review tag:
Thanks, have a great day!
Joshua
Quoted 4 lines
HTH,
Michal
Quoted 8 lines · Joshua Hahn
Quoted 7 lines · Joshua Hahn
Quoted 3 lines
I have to ask, which tree is this based on? I can't seem to find a single tree that contains the "(including those in descendant cgroups)" section anywhere.
It is most likely linux-next which contains a nearby modification from
[1] (or it was based on that regardless).
Quoted 7 lines
Hello Michal,
Thank you, I must have missed linux-next in my searching... that makes a lot of sense! With that, Tao, please feel free to add my review tag:
Reviewed-by Joshua Hahn <[email protected]>
Thanks Michal for the pointer, and Joshua for the tag. Based on linux-next (next-20260717).
Thanks,
Tao
Quoted 7 lines
Thanks, have a great day!
JoshuaQuoted 4 lines
HTH,
Michal
Michal Koutný
maintainerQuoted 8 lines · Tao Cui
From: Tao Cui <[email protected]>
cgroup_base_stat_cputime_show()unconditionally prints a fourth base stat,nice_usec, in addition to usage_usec/user_usec/system_usec, and also prints core_sched.force_idle_usec whenCONFIG_SCHED_COREis enabled. Neither field is currently described in the cpu.stat section ofcgroup-v2.rst, which still states it "always reports the following three stats".
Just to better sense popularity of the fields -- have you found this out by:
a) reading cpu.stat and being confused about semantics of the fields or
b) scanning files/code vs docs looking for discrepancies?
Thanks,
Michal
Quoted 10 lines · Michal Koutný
Quoted 8 lines · Tao Cui
From: Tao Cui <[email protected]>
cgroup_base_stat_cputime_show()unconditionally prints a fourth base stat,nice_usec, in addition to usage_usec/user_usec/system_usec, and also prints core_sched.force_idle_usec whenCONFIG_SCHED_COREis enabled. Neither field is currently described in the cpu.stat section ofcgroup-v2.rst, which still states it "always reports the following three stats".
Quoted 5 lines
Just to better sense popularity of the fields -- have you found this out by:
a) reading cpu.stat and being confused about semantics of the fields or
b) scanning files/code vs docs looking for discrepancies?
(b). I found it while auditing the cgroup cpu controller, comparing what cgroup_base_stat_cputime_show() prints against the cpu.stat docs. nice_usec is emitted unconditionally but not listed there, and the "three stats" count was stale.
The audit is groundwork for a prototype daemon that monitors per-cgroup resource usage and adjusts limits dynamically. The design is inspired by DAMON, but DAMON targets a single resource domain, whereas container workloads need coordinated control across several (cpu, memory, io) — which is why I'm going through the per-controller stat interfaces.
Thanks,
Tao
Quoted 2 lines
Thanks,
Michal