[PATCH] Documentation/cgroup-v2: Update memory.numa_stat description to reflect possible units

[PATCH] Documentation/cgroup-v2: Update memory.numa_stat description to reflect possible units

[Li Zhijian]

The description of the memory.numa_stat file has been updated to clarify
that the output values can be in bytes or pages. This change ensures that
users are aware that the unit of measurement for memory values can vary
and should be verified by consulting the memory.stat

It's known that
workingset_*, pgdemote_* and pgpromote_success are counted in pages

Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 315ede811c9d..5d1d44547409 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1427,7 +1427,7 @@ The following nested keys are defined.
 	types of memory, type-specific details, and other information
 	on the state and past events of the memory management system.
 
-	All memory amounts are in bytes.
+	All memory amounts are in bytes or bytes.
 
 	The entries are ordered to be human readable, and new entries
 	can show up in the middle. Don't rely on items remaining in a
@@ -1673,11 +1673,12 @@ The following nested keys are defined.
 	application performance by combining this information with the
 	application's CPU allocation.
 
-	All memory amounts are in bytes.
-
 	The output format of memory.numa_stat is::
 
-	  type N0=<bytes in node 0> N1=<bytes in node 1> ...
+	  type N0=<value for node 0> N1=<value for node 1> ...
+
+        The 'value' can be in bytes or pages, depending on the specific
+        type of memory. To determine the unit, refer to the memory.stat.
 
 	The entries are ordered to be human readable, and new entries
 	can show up in the middle. Don't rely on items remaining in a
-- 
2.44.0

Re: [PATCH] Documentation/cgroup-v2: Update memory.numa_stat description to reflect possible units

[Waiman Long]

On 1/10/25 7:30 AM, Li Zhijian wrote:
> The description of the memory.numa_stat file has been updated to clarify
> that the output values can be in bytes or pages. This change ensures that
> users are aware that the unit of measurement for memory values can vary
> and should be verified by consulting the memory.stat
>
> It's known that
> workingset_*, pgdemote_* and pgpromote_success are counted in pages
>
> Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>
> ---
>   Documentation/admin-guide/cgroup-v2.rst | 9 +++++----
>   1 file changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
> index 315ede811c9d..5d1d44547409 100644
> --- a/Documentation/admin-guide/cgroup-v2.rst
> +++ b/Documentation/admin-guide/cgroup-v2.rst
> @@ -1427,7 +1427,7 @@ The following nested keys are defined.
>   	types of memory, type-specific details, and other information
>   	on the state and past events of the memory management system.
>   
> -	All memory amounts are in bytes.
> +	All memory amounts are in bytes or bytes.

You mean "bytes or pages". Right?

Cheers,
Longman

Re: [PATCH] Documentation/cgroup-v2: Update memory.numa_stat description to reflect possible units

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 407 bytes --]

On Fri, Jan 10, 2025 at 10:26:40AM -0500, Waiman Long <llong@redhat.com> wrote:
> > -	All memory amounts are in bytes.
> > +	All memory amounts are in bytes or bytes.
> 
> You mean "bytes or pages". Right?

Despite both variant are logically correct, the docs should better say:
+	All memory amounts are in bytes unless said otherwise.
(so that it points to respective explainers).

HTH,
Michal

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH] Documentation/cgroup-v2: Update memory.numa_stat description to reflect possible units

[Zhijian Li (Fujitsu)]

On 10/01/2025 23:35, Michal Koutný wrote:
> On Fri, Jan 10, 2025 at 10:26:40AM -0500, Waiman Long <llong@redhat.com> wrote:
>>> -	All memory amounts are in bytes.
>>> +	All memory amounts are in bytes or bytes.
>>
>> You mean "bytes or pages". Right?
> 
> Despite both variant are logically correct, the docs should better say:
> +	All memory amounts are in bytes unless said otherwise.
> (so that it points to respective explainers).

Michal, Longman


Thank you very much for all your feedback; I will make updates based on Michal's suggestion.

Thanks
Zhijian

> 
> HTH,
> Michal

[PATCH v2] Documentation/cgroup-v2: Update memory.{stat,numa_stat} description to reflect possible units

[Li Zhijian]

The description of the memory.{stat,numa_stat} file has been updated to
clarify that the output values can be in bytes or pages.
This change ensures that users are aware that the unit of measurement for
memory values can vary and should be verified by consulting the memory.stat

It's known that
workingset_*, pg* are counted in pages

Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>a
---
V2: updated the document as suggestion from Michal
    updated subject and commit log
---
 Documentation/admin-guide/cgroup-v2.rst | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 315ede811c9d..0a43be0c32d1 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1427,7 +1427,7 @@ The following nested keys are defined.
 	types of memory, type-specific details, and other information
 	on the state and past events of the memory management system.
 
-	All memory amounts are in bytes.
+	All memory amounts are in bytes unless said otherwise.
 
 	The entries are ordered to be human readable, and new entries
 	can show up in the middle. Don't rely on items remaining in a
@@ -1673,11 +1673,12 @@ The following nested keys are defined.
 	application performance by combining this information with the
 	application's CPU allocation.
 
-	All memory amounts are in bytes.
-
 	The output format of memory.numa_stat is::
 
-	  type N0=<bytes in node 0> N1=<bytes in node 1> ...
+	  type N0=<value for node 0> N1=<value for node 1> ...
+
+        The 'value' can be in bytes or pages, depending on the specific
+        type of memory. To determine the unit, refer to the memory.stat.
 
 	The entries are ordered to be human readable, and new entries
 	can show up in the middle. Don't rely on items remaining in a
-- 
2.44.0

Re: [PATCH v2] Documentation/cgroup-v2: Update memory.{stat,numa_stat} description to reflect possible units

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1632 bytes --]

On Mon, Jan 13, 2025 at 09:05:30AM +0800, Li Zhijian wrote:
> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
> index 315ede811c9d..0a43be0c32d1 100644
> --- a/Documentation/admin-guide/cgroup-v2.rst
> +++ b/Documentation/admin-guide/cgroup-v2.rst
> @@ -1427,7 +1427,7 @@ The following nested keys are defined.
>  	types of memory, type-specific details, and other information
>  	on the state and past events of the memory management system.
>  
> -	All memory amounts are in bytes.
> +	All memory amounts are in bytes unless said otherwise.
                                       "... unless otherwise specified."
>  
>  	The entries are ordered to be human readable, and new entries
>  	can show up in the middle. Don't rely on items remaining in a
> @@ -1673,11 +1673,12 @@ The following nested keys are defined.
>  	application performance by combining this information with the
>  	application's CPU allocation.
>  
> -	All memory amounts are in bytes.
> -
>  	The output format of memory.numa_stat is::
>  
> -	  type N0=<bytes in node 0> N1=<bytes in node 1> ...
> +	  type N0=<value for node 0> N1=<value for node 1> ...
> +
> +        The 'value' can be in bytes or pages, depending on the specific
> +        type of memory. To determine the unit, refer to the memory.stat.
>  
>  	The entries are ordered to be human readable, and new entries
>  	can show up in the middle. Don't rely on items remaining in a

The rest LGTM.

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2] Documentation/cgroup-v2: Update memory.{stat,numa_stat} description to reflect possible units

[Jonathan Corbet]

Li Zhijian <lizhijian@fujitsu.com> writes:

> The description of the memory.{stat,numa_stat} file has been updated to
> clarify that the output values can be in bytes or pages.
> This change ensures that users are aware that the unit of measurement for
> memory values can vary and should be verified by consulting the memory.stat
>
> It's known that
> workingset_*, pg* are counted in pages
>
> Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>a
> ---
> V2: updated the document as suggestion from Michal
>     updated subject and commit log
> ---
>  Documentation/admin-guide/cgroup-v2.rst | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
> index 315ede811c9d..0a43be0c32d1 100644
> --- a/Documentation/admin-guide/cgroup-v2.rst
> +++ b/Documentation/admin-guide/cgroup-v2.rst
> @@ -1427,7 +1427,7 @@ The following nested keys are defined.
>  	types of memory, type-specific details, and other information
>  	on the state and past events of the memory management system.
>  
> -	All memory amounts are in bytes.
> +	All memory amounts are in bytes unless said otherwise.
>  
>  	The entries are ordered to be human readable, and new entries
>  	can show up in the middle. Don't rely on items remaining in a
> @@ -1673,11 +1673,12 @@ The following nested keys are defined.
>  	application performance by combining this information with the
>  	application's CPU allocation.
>  
> -	All memory amounts are in bytes.
> -
>  	The output format of memory.numa_stat is::
>  
> -	  type N0=<bytes in node 0> N1=<bytes in node 1> ...
> +	  type N0=<value for node 0> N1=<value for node 1> ...
> +
> +        The 'value' can be in bytes or pages, depending on the specific
> +        type of memory. To determine the unit, refer to the memory.stat.

This seems like useful information - but can we really not give better
guidance to our readers on how to interpret this value?  What in "the
memory.stat" will tell them which units are in use?

(Even better, could we fix the code to always return the same units
without breaking something somewhere?)

Thanks,

jon

Re: [PATCH v2] Documentation/cgroup-v2: Update memory.{stat,numa_stat} description to reflect possible units

[Zhijian Li (Fujitsu)]

Hi Jonathan,


On 14/01/2025 01:49, Jonathan Corbet wrote:
> Li Zhijian <lizhijian@fujitsu.com> writes:
> 
>> The description of the memory.{stat,numa_stat} file has been updated to
>> clarify that the output values can be in bytes or pages.
>> This change ensures that users are aware that the unit of measurement for
>> memory values can vary and should be verified by consulting the memory.stat
>>
>> It's known that
>> workingset_*, pg* are counted in pages
>>
>> Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>a
>> ---
>> V2: updated the document as suggestion from Michal
>>      updated subject and commit log
>> ---
>>   Documentation/admin-guide/cgroup-v2.rst | 9 +++++----
>>   1 file changed, 5 insertions(+), 4 deletions(-)
>>
>> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
>> index 315ede811c9d..0a43be0c32d1 100644
>> --- a/Documentation/admin-guide/cgroup-v2.rst
>> +++ b/Documentation/admin-guide/cgroup-v2.rst
>> @@ -1427,7 +1427,7 @@ The following nested keys are defined.
>>   	types of memory, type-specific details, and other information
>>   	on the state and past events of the memory management system.
>>   
>> -	All memory amounts are in bytes.
>> +	All memory amounts are in bytes unless said otherwise.
>>   
>>   	The entries are ordered to be human readable, and new entries
>>   	can show up in the middle. Don't rely on items remaining in a
>> @@ -1673,11 +1673,12 @@ The following nested keys are defined.
>>   	application performance by combining this information with the
>>   	application's CPU allocation.
>>   
>> -	All memory amounts are in bytes.
>> -
>>   	The output format of memory.numa_stat is::
>>   
>> -	  type N0=<bytes in node 0> N1=<bytes in node 1> ...
>> +	  type N0=<value for node 0> N1=<value for node 1> ...
>> +
>> +        The 'value' can be in bytes or pages, depending on the specific
>> +        type of memory. To determine the unit, refer to the memory.stat.
> 
> This seems like useful information - but can we really not give better
> guidance to our readers on how to interpret this value?  What in "the
> memory.stat" will tell them which units are in use?

Let me quote a piece of the numa.stat:

In pages:
>          pgdemote_khugepaged                                                   
>                Number of pages demoted by khugepaged.

In bytes:
>          file                                                                  
>                Amount of memory used to cache filesystem data,                 
>                including tmpfs and shared memory. 

Prior to this reference to `memory.stat`, the previous `memory.numa_stat` also
relied on `memory.stat` to determine which entries were present.
Therefore, adding this current reference to `memory.stat` does not introduce
additional complexity.

1680         The 'value' can be in bytes or pages, depending on the specific
1681         type of memory. To determine the unit, refer to the memory.stat.
1682
1683         The entries are ordered to be human readable, and new entries
1684         can show up in the middle. Don't rely on items remaining in a
1685         fixed position; use the keys to look up specific values!
1686
1687         The entries can refer to the memory.stat.   <<< the original reference


> (Even better, could we fix the code to always return the same units
> without breaking something somewhere?)


Of course, I am not opposed to having all entries use the same unit.
At a glance, there are quite a few entries within `memory.stat` that are
actually measured in pages. Do we truly request to this significant modification?


Thanks
Zhijian

> 
> Thanks,
> 
> jon

Re: [PATCH v2] Documentation/cgroup-v2: Update memory.{stat,numa_stat} description to reflect possible units

[Jonathan Corbet]

"Zhijian Li (Fujitsu)" <lizhijian@fujitsu.com> writes:

> Hi Jonathan,
>
>
> On 14/01/2025 01:49, Jonathan Corbet wrote:
>> Li Zhijian <lizhijian@fujitsu.com> writes:
>> 
>>> The description of the memory.{stat,numa_stat} file has been updated to
>>> clarify that the output values can be in bytes or pages.
>>> This change ensures that users are aware that the unit of measurement for
>>> memory values can vary and should be verified by consulting the memory.stat
>>>
>>> It's known that
>>> workingset_*, pg* are counted in pages
>>>
>>> Signed-off-by: Li Zhijian <lizhijian@fujitsu.com>a
>>> ---
>>> V2: updated the document as suggestion from Michal
>>>      updated subject and commit log
>>> ---
>>>   Documentation/admin-guide/cgroup-v2.rst | 9 +++++----
>>>   1 file changed, 5 insertions(+), 4 deletions(-)
>>>
>>> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
>>> index 315ede811c9d..0a43be0c32d1 100644
>>> --- a/Documentation/admin-guide/cgroup-v2.rst
>>> +++ b/Documentation/admin-guide/cgroup-v2.rst
>>> @@ -1427,7 +1427,7 @@ The following nested keys are defined.
>>>   	types of memory, type-specific details, and other information
>>>   	on the state and past events of the memory management system.
>>>   
>>> -	All memory amounts are in bytes.
>>> +	All memory amounts are in bytes unless said otherwise.
>>>   
>>>   	The entries are ordered to be human readable, and new entries
>>>   	can show up in the middle. Don't rely on items remaining in a
>>> @@ -1673,11 +1673,12 @@ The following nested keys are defined.
>>>   	application performance by combining this information with the
>>>   	application's CPU allocation.
>>>   
>>> -	All memory amounts are in bytes.
>>> -
>>>   	The output format of memory.numa_stat is::
>>>   
>>> -	  type N0=<bytes in node 0> N1=<bytes in node 1> ...
>>> +	  type N0=<value for node 0> N1=<value for node 1> ...
>>> +
>>> +        The 'value' can be in bytes or pages, depending on the specific
>>> +        type of memory. To determine the unit, refer to the memory.stat.
>> 
>> This seems like useful information - but can we really not give better
>> guidance to our readers on how to interpret this value?  What in "the
>> memory.stat" will tell them which units are in use?
>
> Let me quote a piece of the numa.stat:
>
> In pages:
>>          pgdemote_khugepaged                                                   
>>                Number of pages demoted by khugepaged.
>
> In bytes:
>>          file                                                                  
>>                Amount of memory used to cache filesystem data,                 
>>                including tmpfs and shared memory. 
>
> Prior to this reference to `memory.stat`, the previous `memory.numa_stat` also
> relied on `memory.stat` to determine which entries were present.
> Therefore, adding this current reference to `memory.stat` does not introduce
> additional complexity.
>
> 1680         The 'value' can be in bytes or pages, depending on the specific
> 1681         type of memory. To determine the unit, refer to the memory.stat.
> 1682
> 1683         The entries are ordered to be human readable, and new entries
> 1684         can show up in the middle. Don't rely on items remaining in a
> 1685         fixed position; use the keys to look up specific values!
> 1686
> 1687         The entries can refer to the memory.stat.   <<< the original reference

...but neither does it help our reader.  Can we at least point to
something that would help them to make sense of this value?

>> (Even better, could we fix the code to always return the same units
>> without breaking something somewhere?)
>
> Of course, I am not opposed to having all entries use the same unit.
> At a glance, there are quite a few entries within `memory.stat` that are
> actually measured in pages. Do we truly request to this significant modification?

No, I am not asking you to do that - I was just thinking that it could
be a good idea.  But there may be reasons for why things are the way
they are, and I do not know if such a change would be accepted by the
relevant maintainers or not.

jon

Re: [PATCH v2] Documentation/cgroup-v2: Update memory.{stat,numa_stat} description to reflect possible units

[Tejun Heo]

Hello,

On Thu, Jan 16, 2025 at 05:50:54AM +0000, Zhijian Li (Fujitsu) wrote:
...
> Let me quote a piece of the numa.stat:
> 
> In pages:
> >          pgdemote_khugepaged                                                   
> >                Number of pages demoted by khugepaged.

If this is the only entry in pages, I'm not sure the proposed document
update is the best one. The above can have an easy alternative description
"the number of times khugepaged demoted a huge page" - ie. indicate that it
is an event counter instead, which is a plausible and likely more intuitive
definition anyway given that a "huge page" can plausibly be of different
sizes. With the key name and matching description, I'm not sure it's
violating the rule that all *sizes* are expressed in bytes.

Thanks.

-- 
tejun

Re: [PATCH v2] Documentation/cgroup-v2: Update memory.{stat,numa_stat} description to reflect possible units

[Zhijian Li (Fujitsu)]

+

On 17/01/2025 01:19, Tejun Heo wrote:
> Hello,
> 
> On Thu, Jan 16, 2025 at 05:50:54AM +0000, Zhijian Li (Fujitsu) wrote:
> ...
>> Let me quote a piece of the numa.stat:
>>
>> In pages:
>>>           pgdemote_khugepaged
>>>                 Number of pages demoted by khugepaged.
> 
> If this is the only entry in pages, I'm not sure the proposed document
> update is the best one. 

I asked the ChatGPT with the contents in memory.stat, the ChatGPT answered:
In short, There are 28 entries in bytes and 37 entries in pages.

```
Based on the list provided, here are the counts for each:

### Entries in Bytes

There are 28 entries in bytes:

1. anon
2. file
3. kernel
4. kernel_stack
5. pagetables
6. sec_pagetables
7. percpu
8. sock
9. vmalloc
10. shmem
11. zswap
12. zswapped
13. file_mapped
14. file_dirty
15. file_writeback
16. swapcached
17. anon_thp
18. file_thp
19. shmem_thp
20. inactive_anon
21. active_anon
22. inactive_file
23. active_file
24. unevictable
25. slab_reclaimable
26. slab_unreclaimable
27. slab
28. hugetlb

### Entries in Pages

There are 37 entries in pages:

1. workingset_refault_anon
2. workingset_refault_file
3. workingset_activate_anon
4. workingset_activate_file
5. workingset_restore_anon
6. workingset_restore_file
7. workingset_nodereclaim
8. pgscan
9. pgsteal
10. pgscan_kswapd
11. pgscan_direct
12. pgscan_khugepaged
13. pgsteal_kswapd
14. pgsteal_direct
15. pgsteal_khugepaged
16. pgfault
17. pgmajfault
18. pgrefill
19. pgactivate
20. pgdeactivate
21. pglazyfree
22. pglazyfreed
23. swpin_zero
24. swpout_zero
25. zswpin
26. zswpout
27. zswpwb
28. thp_fault_alloc
29. thp_collapse_alloc
30. thp_swpout
31. thp_swpout_fallback
32. numa_pages_migrated
33. numa_pte_updates
34. numa_hint_faults
35. pgdemote_kswapd
36. pgdemote_direct
37. pgdemote_khugepaged

```


The above can have an easy alternative description
> "the number of times khugepaged demoted a huge page" - ie. indicate that it
> is an event counter instead, which is a plausible and likely more intuitive
> definition anyway given that a "huge page" can plausibly be of different
> sizes. With the key name and matching description, I'm not sure it's
> violating the rule that all *sizes* are expressed in bytes.
> 
> Thanks.
>