Skip to contentSkip to conversation

cgroup/cpu: document cpu.stat nice_usec and core_sched.force_idle_usec

PATCH In review Tao Cui 3 participants 7 messages Jul 18 – Jul 21

Subsystems (2)
lore
Share & tools
lore

Tao Cui

author
#0 lore raw

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
index 0df15a672cf3..778b759dd892 100644
@@ -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
#1 lore raw
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 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".

Quoted 8 lines

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.

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
index 0df15a672cf3..778b759dd892 100644

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

maintainer
#2 lore raw
Quoted 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

[1] https://lore.kernel.org/lkml/[email protected]/

Reviewed-by
#3 lore raw
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).

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

[1] https://lore.kernel.org/lkml/[email protected]/

author
#4 lore raw
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:

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!
Joshua

Quoted 4 lines

HTH,
Michal

[1] https://lore.kernel.org/lkml/[email protected]/

maintainer
#5 lore raw
In reply to Tao Cui
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 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".

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

author
#6 lore raw
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 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".

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