Hello Roman,
I wish to add documentation to cgroups(7) for the cgroup.stat file
that you added in Linux 4.14. I wrote some text based on your text
added to the cgroup-v2.txt file, but added some pieces, and also have
a question (see below). The plain-text version for (easy review)
is shown below. Could you please review this text? (Please note
the FIXME!)
The branch containing the pending cgroups(7) changes can be found at :
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=draft_cgroup_updates
[[
Cgroups v2 cgroup.stat file
Each cgroup in the v2 hierarchy contains a read-only
cgroup.stat file (first introduced in Linux 4.14) that consists
of lines containing key-value pairs. The following keys cur‐
rently appear in this file:
nr_descendants
This is the total number of visible (i.e., living)
descendant cgroups underneath this cgroup.
┌─────────────────────────────────────────────────────┐
│FIXME │
├─────────────────────────────────────────────────────┤
│For the following text on nr_dying_descendants, it │
│would I think be helpful to describe a condrete │
│example of when one might see nr_dying_descendants a │
│nonzero value for this key. Ideally, the example │
│would be one that the reader could easily reproduce. │
│Is there such an example? │
└─────────────────────────────────────────────────────┘
nr_dying_descendants
This is the total number of dying descendant cgroups
underneath this cgroup. A cgroup enters the dying state
after being deleted. It remains in that state for an
undefined period (which will depend on system load)
before being destroyed.
A process can't be made a member of a dying cgroup, and
a dying cgroup can't be brought back to life.
]]
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Hello, Michael!
Thank you for working on this!
Please, find my comments below.
On Tue, Jan 02, 2018 at 07:22:33PM +0100, Michael Kerrisk (man-pages) wrote:
> Hello Roman,
>
> I wish to add documentation to cgroups(7) for the cgroup.stat file
> that you added in Linux 4.14. I wrote some text based on your text
> added to the cgroup-v2.txt file, but added some pieces, and also have
> a question (see below). The plain-text version for (easy review)
> is shown below. Could you please review this text? (Please note
> the FIXME!)
>
> The branch containing the pending cgroups(7) changes can be found at :
> https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=draft_cgroup_updates
>
> [[
> Cgroups v2 cgroup.stat file
> Each cgroup in the v2 hierarchy contains a read-only
> cgroup.stat file (first introduced in Linux 4.14) that consists
> of lines containing key-value pairs. The following keys cur‐
> rently appear in this file:
>
> nr_descendants
> This is the total number of visible (i.e., living)
> descendant cgroups underneath this cgroup.
>
> ┌─────────────────────────────────────────────────────┐
> │FIXME │
> ├─────────────────────────────────────────────────────┤
> │For the following text on nr_dying_descendants, it │
> │would I think be helpful to describe a condrete │
> │example of when one might see nr_dying_descendants a │
> │nonzero value for this key. Ideally, the example │
> │would be one that the reader could easily reproduce. │
> │Is there such an example? │
> └─────────────────────────────────────────────────────┘
Hm, basically any cgroup which had some pagecache, associated during the
lifetime, will spend some time in the dying state. This means that for
most cgroups this number will be non-zero for some amount of time,
which depends on global memory pressure.
It's also very implementation-defined, and will be likely changed
in the following kernel versions.
So, I'm not sure, that such an example will be useful for a user.
Until this number is huge and constantly growing, it shouldn't be
interesting for an user at all.
>
> nr_dying_descendants
> This is the total number of dying descendant cgroups
> underneath this cgroup. A cgroup enters the dying state
> after being deleted. It remains in that state for an
> undefined period (which will depend on system load)
> before being destroyed.
>
> A process can't be made a member of a dying cgroup, and
> a dying cgroup can't be brought back to life.
So, maybe it worth it to add a statement, that some amount of dying cgroups
is normal and it's not a signal of any problem?
Otherwise looks very good to me.
Thank you!
Roman
Hello Roman,
On 01/02/2018 10:57 PM, Roman Gushchin wrote:
> Hello, Michael!
>
> Thank you for working on this!
You're welcome. Thanks for reviewing the text!
> Please, find my comments below.
>
> On Tue, Jan 02, 2018 at 07:22:33PM +0100, Michael Kerrisk (man-pages) wrote:
>> Hello Roman,
>>
>> I wish to add documentation to cgroups(7) for the cgroup.stat file
>> that you added in Linux 4.14. I wrote some text based on your text
>> added to the cgroup-v2.txt file, but added some pieces, and also have
>> a question (see below). The plain-text version for (easy review)
>> is shown below. Could you please review this text? (Please note
>> the FIXME!)
>>
>> The branch containing the pending cgroups(7) changes can be found at :
>> https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=draft_cgroup_updates
>>
>> [[
>> Cgroups v2 cgroup.stat file
>> Each cgroup in the v2 hierarchy contains a read-only
>> cgroup.stat file (first introduced in Linux 4.14) that consists
>> of lines containing key-value pairs. The following keys cur‐
>> rently appear in this file:
>>
>> nr_descendants
>> This is the total number of visible (i.e., living)
>> descendant cgroups underneath this cgroup.
>>
>> ┌─────────────────────────────────────────────────────┐
>> │FIXME │
>> ├─────────────────────────────────────────────────────┤
>> │For the following text on nr_dying_descendants, it │
>> │would I think be helpful to describe a condrete │
>> │example of when one might see nr_dying_descendants a │
>> │nonzero value for this key. Ideally, the example │
>> │would be one that the reader could easily reproduce. │
>> │Is there such an example? │
>> └─────────────────────────────────────────────────────┘
>
> Hm, basically any cgroup which had some pagecache, associated during the
> lifetime, will spend some time in the dying state. This means that for
> most cgroups this number will be non-zero for some amount of time,
> which depends on global memory pressure.
> It's also very implementation-defined, and will be likely changed
> in the following kernel versions.
>
> So, I'm not sure, that such an example will be useful for a user.
> Until this number is huge and constantly growing, it shouldn't be
> interesting for an user at all.
Fair enough. I added some vague text about resources needing to be freed
before the cgroup is destroyed. See below.
>> nr_dying_descendants
>> This is the total number of dying descendant cgroups
>> underneath this cgroup. A cgroup enters the dying state
>> after being deleted. It remains in that state for an
>> undefined period (which will depend on system load)
>> before being destroyed.
>>
>> A process can't be made a member of a dying cgroup, and
>> a dying cgroup can't be brought back to life.
>
> So, maybe it worth it to add a statement, that some amount of dying cgroups
> is normal and it's not a signal of any problem?
Okay, I added some text along those lines. The first paragraph now reads:
nr_dying_descendants
This is the total number of dying descendant cgroups
underneath this cgroup. A cgroup enters the dying state
after being deleted. It remains in that state for an
undefined period (which will depend on system load)
while resources are freed before the cgroup is
destroyed. Note that the presence of some cgroups in
the dying state is normal, and is not indicative of any
problem.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
Hello, Michael!
> > Hm, basically any cgroup which had some pagecache, associated during the
> > lifetime, will spend some time in the dying state. This means that for
> > most cgroups this number will be non-zero for some amount of time,
> > which depends on global memory pressure.
> > It's also very implementation-defined, and will be likely changed
> > in the following kernel versions.
> >
> > So, I'm not sure, that such an example will be useful for a user.
> > Until this number is huge and constantly growing, it shouldn't be
> > interesting for an user at all.
>
> Fair enough. I added some vague text about resources needing to be freed
> before the cgroup is destroyed. See below.
>
>
> >> nr_dying_descendants
> >> This is the total number of dying descendant cgroups
> >> underneath this cgroup. A cgroup enters the dying state
> >> after being deleted. It remains in that state for an
> >> undefined period (which will depend on system load)
> >> before being destroyed.
> >>
> >> A process can't be made a member of a dying cgroup, and
> >> a dying cgroup can't be brought back to life.
> >
> > So, maybe it worth it to add a statement, that some amount of dying cgroups
> > is normal and it's not a signal of any problem?
>
> Okay, I added some text along those lines. The first paragraph now reads:
>
> nr_dying_descendants
> This is the total number of dying descendant cgroups
> underneath this cgroup. A cgroup enters the dying state
> after being deleted. It remains in that state for an
> undefined period (which will depend on system load)
> while resources are freed before the cgroup is
> destroyed. Note that the presence of some cgroups in
> the dying state is normal, and is not indicative of any
> problem.
Looks good to me!
Reviewed-by: Roman Gushchin <[email protected]>
Thank you!