Re: [PATCH] docs: iostats: Update introduction with flush fields

[Randy Dunlap <rdunlap@infradead.org>]

Hi,

On 2/13/25 5:39 PM, David Reaver wrote:
> Counters for flush requests were added to the kernel in
> b6866318657 ("block: add iostat counters for flush requests") [1]. While
> iostats.rst was updated with descriptions for the new fields, the
> introduction still mentions 15 fields instead of 17.
> 
> Correct the introduction to state that there are 17 fields instead of 15.
> Also, replace the 2.4 vs. 2.6+ comparison with a distinction between
> /proc/diskstats and the sysfs stat file.
> 
> Link: https://lore.kernel.org/lkml/157433282607.7928.5202409984272248322.stgit@buzz/T/ [1]
> 
> Signed-off-by: David Reaver <me@davidreaver.com>
> ---
> 
> I noticed this small discrepancy while writing an observability tool
> that uses /proc/diskstats. I did a double take because I noticed the
> extra fields in my own system's /proc/diskstats while I was reading this
> doc, but _before_ I got to the descriptions for fields 16 and 17.
> 
> I think the discussion of historical formats for 2.4, 2.6, and 4.18 in
> this document is confusing and not very useful. If you'd like, I'm happy
> to make a patch that rewrites the intro to simplify it and remove
> discussion of the historical formats.

Please do IMO.

>  Documentation/admin-guide/iostats.rst | 33 +++++++++++++++------------
>  1 file changed, 18 insertions(+), 15 deletions(-)
> 
> diff --git a/Documentation/admin-guide/iostats.rst b/Documentation/admin-guide/iostats.rst
> index 609a3201fd4e..1df7961bdc89 100644
> --- a/Documentation/admin-guide/iostats.rst
> +++ b/Documentation/admin-guide/iostats.rst
> @@ -34,6 +34,9 @@ Here are examples of these different formats::
>     4.18+ diskstats:
>        3    0   hda 446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 23705160 0 0 0 0
>  
> +   5.5+ diskstats:
> +      3    0   hda 446216 784926 9550688 4382310 424847 312726 5922052 19310380 0 3376340 23705160 0 0 0 0 0 0
> +
>  On 2.4 you might execute ``grep 'hda ' /proc/partitions``. On 2.6+, you have
>  a choice of ``cat /sys/block/hda/stat`` or ``grep 'hda ' /proc/diskstats``.
>  
> @@ -43,21 +46,21 @@ be a better choice if you are watching a large number of disks because
>  you'll avoid the overhead of 50, 100, or 500 or more opens/closes with
>  each snapshot of your disk statistics.
>  
> -In 2.4, the statistics fields are those after the device name. In
> -the above example, the first field of statistics would be 446216.
> -By contrast, in 2.6+ if you look at ``/sys/block/hda/stat``, you'll
> -find just the 15 fields, beginning with 446216.  If you look at
> -``/proc/diskstats``, the 15 fields will be preceded by the major and
> -minor device numbers, and device name.  Each of these formats provides
> -15 fields of statistics, each meaning exactly the same things.
> -All fields except field 9 are cumulative since boot.  Field 9 should
> -go to zero as I/Os complete; all others only increase (unless they
> -overflow and wrap). Wrapping might eventually occur on a very busy
> -or long-lived system; so applications should be prepared to deal with
> -it. Regarding wrapping, the types of the fields are either unsigned
> -int (32 bit) or unsigned long (32-bit or 64-bit, depending on your
> -machine) as noted per-field below. Unless your observations are very
> -spread in time, these fields should not wrap twice before you notice it.
> +In ``/proc/diskstats``, the statistics fields are those after the device
> +name. In the above example, the first field of statistics would
> +be 446216. By contrast, in ``/sys/block/hda/stat`` you'll find just the
> +17 fields, beginning with 446216. If you look at ``/proc/diskstats``,
> +the 17 fields will be preceded by the major and minor device numbers,
> +and device name. Each of these formats provides 17 fields of statistics,
> +each meaning exactly the same things. All fields except field 9 are
> +cumulative since boot. Field 9 should go to zero as I/Os complete; all
> +others only increase (unless they overflow and wrap). Wrapping might
> +eventually occur on a very busy or long-lived system; so applications

I prefer a comma instead of semi-colon above. Yes, I know, it was already
like this.

> +should be prepared to deal with it. Regarding wrapping, the types of the
> +fields are either unsigned int (32 bit) or unsigned long (32-bit or
> +64-bit, depending on your machine) as noted per-field below. Unless your
> +observations are very spread in time, these fields should not wrap twice
> +before you notice it.
>  
>  Each set of stats only applies to the indicated device; if you want
>  system-wide stats you'll have to find all the devices and sum them all up.
> 
> base-commit: a64dcfb451e254085a7daee5fe51bf22959d52d3
> 

LGTM. Thanks.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy