Re: cgroups(7): documenting cgroup.stat

[Roman Gushchin]

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