Re: cgroups(7): documenting cgroup.stat

[Roman Gushchin <guro@fb.com>]

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