Documentation/admin-guide/iostats.rst

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/iostats.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/iostats.rst
Extension
.rst
Size
8592 bytes
Lines
188
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=====================
I/O statistics fields
=====================

The kernel exposes disk statistics via ``/proc/diskstats`` and
``/sys/block/<device>/stat``. These stats are usually accessed via tools
such as ``sar`` and ``iostat``.

Here are examples using a disk with two partitions::

   /proc/diskstats:
     259       0 nvme0n1 255999 814 12369153 47919 996852 81 36123024 425995 0 301795 580470 0 0 0 0 60602 106555
     259       1 nvme0n1p1 492 813 17572 96 848 81 108288 210 0 76 307 0 0 0 0 0 0
     259       2 nvme0n1p2 255401 1 12343477 47799 996004 0 36014736 425784 0 344336 473584 0 0 0 0 0 0

   /sys/block/nvme0n1/stat:
     255999 814 12369153 47919 996858 81 36123056 426009 0 301809 580491 0 0 0 0 60605 106562

   /sys/block/nvme0n1/nvme0n1p1/stat:
     492 813 17572 96 848 81 108288 210 0 76 307 0 0 0 0 0 0

Both files contain the same 17 statistics. ``/sys/block/<device>/stat``
contains the fields for ``<device>``. In ``/proc/diskstats`` the fields
are prefixed with the major and minor device numbers and the device
name. In the example above, the first stat value for ``nvme0n1`` is
255999 in both files.

The sysfs ``stat`` file is efficient for monitoring a small, known set
of disks. If you're tracking a large number of devices,
``/proc/diskstats`` is often the better choice since it avoids the
overhead of opening and closing multiple files for each snapshot.

All fields are cumulative, monotonic counters, except for field 9, which
resets to zero as I/Os complete. The remaining fields reset at boot, on
device reattachment or reinitialization, or when the underlying counter
overflows. Applications reading these counters should detect and handle
resets when comparing stat snapshots.

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.

Field  1 -- # of reads completed (unsigned long)
    This is the total number of reads completed successfully.

Field  2 -- # of reads merged, field 6 -- # of writes merged (unsigned long)
    Reads and writes which are adjacent to each other may be merged for
    efficiency.  Thus two 4K reads may become one 8K read before it is
    ultimately handed to the disk, and so it will be counted (and queued)
    as only one I/O.  This field lets you know how often this was done.

Field  3 -- # of sectors read (unsigned long)
    This is the total number of sectors read successfully.

Field  4 -- # of milliseconds spent reading (unsigned int)
    This is the total number of milliseconds spent by all reads (as
    measured from blk_mq_alloc_request() to __blk_mq_end_request()).

Field  5 -- # of writes completed (unsigned long)
    This is the total number of writes completed successfully.

Field  6 -- # of writes merged  (unsigned long)
    See the description of field 2.

Field  7 -- # of sectors written (unsigned long)
    This is the total number of sectors written successfully.

Field  8 -- # of milliseconds spent writing (unsigned int)
    This is the total number of milliseconds spent by all writes (as
    measured from blk_mq_alloc_request() to __blk_mq_end_request()).

Annotation

Implementation Notes