Date: Tue, 2 Jan 2018 21:57:33 +0000
From: Roman Gushchin <guro@fb.com>
To: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
CC: Tejun Heo <tj@kernel.org>, "Serge E. Hallyn" <serge@hallyn.com>,
        lkml <linux-kernel@vger.kernel.org>, <cgroups@vger.kernel.org>,
        linux-man <linux-man@vger.kernel.org>
Subject: Re: cgroups(7): documenting cgroup.stat
Message-ID: <20180102215726.GA2606@castle>
References: <196c0cca-b573-8c65-2b5f-66376f79a836@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <196c0cca-b573-8c65-2b5f-66376f79a836@gmail.com>
User-Agent: Mutt/1.9.1 (2017-09-22)
SpamDiagnosticOutput: 1:99
SpamDiagnosticMetadata: NSPM
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 02 Jan 2018 21:57:44.8111 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: c3c7d85d-0bf5-4503-34af-08d5522bdb79
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 8ae927fe-1255-47a7-a2af-5f3a069daaa2
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BL2PR15MB1076
X-OriginatorOrg: fb.com
X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:,, definitions=2018-01-02_16:,,
 signatures=0
X-Proofpoint-Spam-Reason: safe
X-FB-Internal: Safe
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
Return-Path: <linux-kernel-owner@vger.kernel.org>

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