block/stat.txt
Subsystems (2)
PATCH 1/1 block/stat.txt
I couldn't find any docs explaining the contents of /sys/block/<dev>/stat, so I wrote up the following. I'm not completely sure it's accurate - Jens, could you give a yea or nay on this?
In particular, the counts of read/write IOs and read/write sectors are incremented in different places - it looks like they both increment as the request is being finished, but I'm not completely sure of that.
-andy
---
# HG changeset patch
# User [email protected]
# Node ID 28202adc17846b087209ce937fa5cd0f2f4ffbbb
# Parent 03055821672a46deb8291db0cf719e39c2f0d48e Documentation/block/stat.txt: document contents of /sys/block/<dev>/stat
Documentation/block/stat.txt new file +80 -0
@@ -0,0 +1,80 @@ +Block layer statistics in /sys/block/<dev>/stat +=============================================== + +This file documents the contents of the /sys/block/<dev>/stat file. + +The stat file provides several statistics about the state of block +device <dev>. + +Q. Why are there multiple statistics in a single file? Doesn't sysfs + normally contain a single value per file? +A. By having a single file, the kernel can guarantee that the statistics + represent a consistent snapshot of the state of the device. If the + statistics were exported as multiple files containing one statistic + each, it would be impossible to guarantee that a set of readings + represent a single point in time. + +The stat file consists of a single line of text containing 11 decimal +values separated by whitespace. The fields are summarized in the +following table, and described in more detail below. + +Name units description +---- ----- ----------- +read I/Os requests number of read I/Os processed +read merges requests number of read I/Os merged with in-queue I/O +read sectors blocks number of sectors read +read ticks milliseconds total wait time for read requests +write I/Os requests number of write I/Os processed +write merges requests number of write I/Os merged with in-queue I/O +write sectors blocks number of sectors written +write ticks milliseconds total wait time for write requests +in_flight requests number of I/Os currently in flight +io_ticks milliseconds total time this block device has been active +time_in_queue milliseconds total wait time for all requests + +read I/Os, write I/Os +===================== + +These values increment when an I/O request completes. + +read merges, write merges +========================= + +These values increment when an I/O request is merged with an +already-queued I/O request. + +read sectors, write sectors +=========================== + +These values count the number of blocks read from or written to this +block device. The "blocks" in question are the standard UNIX 512-byte +blocks, not any device-specific block size. The counters are +incremented when the I/O completes. + +read ticks, write ticks +======================= + +These values count the number of milliseconds that I/O requests have +waited on this block device. If there are multiple I/O requests waiting, +these values will increase at a rate greater than 1000/second; for +example, if 60 read requests wait for an average of 30 ms, the read_ticks +field will increase by 60*30 = 1800. + +in_flight +========= + +This value counts the number of currently-queued I/O requests. + +io_ticks +======== + +This value counts the number of milliseconds during which the device has +had I/O requests queued. + +time_in_queue +============= + +This value counts the number of milliseconds that I/O requests have waited +on this block device. If there are multiple I/O requests waiting, this +value will increase as the product of the number of milliseconds times the +number of requests waiting (see "read ticks" above for an example).
Quoted 7 lines · Andy Isaacson
I couldn't find any docs explaining the contents of /sys/block/<dev>/stat, so I wrote up the following. I'm not completely sure it's accurate - Jens, could you give a yea or nay on this?
In particular, the counts of read/write IOs and read/write sectors are incremented in different places - it looks like they both increment as the request is being finished, but I'm not completely sure of that.
Overall it looks very nice, you basically all of it right. And thanks for doing it btw, it's a good addition to the documentation. A few small comments follows:
Documentation/block/stat.txt line 25
Quoted 5 lines
Documentation/block/stat.txt new file +5
-0+Name units description +---- ----- ----------- +read I/Os requests number of read I/Os processed +read merges requests number of read I/Os merged with in-queue I/O +read sectors blocks number of sectors read
The unit here should just read 'sectors', blocks usually refers to a file system block.
Documentation/block/stat.txt line 44
Quoted 10 lines
Documentation/block/stat.txt new file +10
-0+read I/Os, write I/Os +===================== + +These values increment when an I/O request completes. + +read merges, write merges +========================= + +These values increment when an I/O request is merged with an +already-queued I/O request.
Both correct, good!
Documentation/block/stat.txt line 52
Quoted 7 lines
Documentation/block/stat.txt new file +7
-0+read sectors, write sectors +=========================== + +These values count the number of blocks read from or written to this +block device. The "blocks" in question are the standard UNIX 512-byte +blocks, not any device-specific block size. The counters are +incremented when the I/O completes.
These standard 512-b blocks we just call sectors in Linux.
Documentation/block/stat.txt line 66
Quoted 4 lines
Documentation/block/stat.txt new file +4
-0+in_flight +========= + +This value counts the number of currently-queued I/O requests.
A little confusing - it's the number of in flight io at the driver/device end, that is after the block layer. One could read the above as total in flight (total queued in the queue for the device), which is a very different number.
Signature · 1 line
Jens Axboe
Andrew - the below should replace block-stat.txt.diff. You might want to use the Mercurial changelog (below) rather than the email body.
Quoted 8 lines · Jens Axboe
Quoted 3 lines · Andy Isaacson
I couldn't find any docs explaining the contents of /sys/block/<dev>/stat, so I wrote up the following. I'm not completely sure it's accurate - Jens, could you give a yea or nay on this?
Overall it looks very nice, you basically all of it right. And thanks for doing it btw, it's a good addition to the documentation. A few small comments follows:
Thank you for your comments. The easy ones were easy to incorporate, but let me get one more bit of feedback:
Quoted 9 lines
Review
Quoted 4 lines
(quoted diff) +4
-0+in_flight +========= + +This value counts the number of currently-queued I/O requests.A little confusing - it's the number of in flight io at the driver/device end, that is after the block layer. One could read the above as total in flight (total queued in the queue for the device), which is a very different number.
I wrote from misunderstanding, so it's no suprise what I wrote was wrong. :) Is "number of requests in the queue" available somewhere?
How does this sound instead of the above?
+in_flight
+=========
+
+This value counts the number of I/O requests that have been issued to +the device driver but have not yet completed. It does not include I/O +requests that are in the queue but not yet issued to the device driver.
Complete patch below.
-andy
# HG changeset patch
# User [email protected]
# Node ID b3b07fba68e5d19602696e88f8ce540ddd6ef384
# Parent 03055821672a46deb8291db0cf719e39c2f0d48e Documentation/block/stat.txt: document contents of /sys/block/<dev>/stat
Documentation/block/stat.txt new file +82 -0
@@ -0,0 +1,82 @@ +Block layer statistics in /sys/block/<dev>/stat +=============================================== + +This file documents the contents of the /sys/block/<dev>/stat file. + +The stat file provides several statistics about the state of block +device <dev>. + +Q. Why are there multiple statistics in a single file? Doesn't sysfs + normally contain a single value per file? +A. By having a single file, the kernel can guarantee that the statistics + represent a consistent snapshot of the state of the device. If the + statistics were exported as multiple files containing one statistic + each, it would be impossible to guarantee that a set of readings + represent a single point in time. + +The stat file consists of a single line of text containing 11 decimal +values separated by whitespace. The fields are summarized in the +following table, and described in more detail below. + +Name units description +---- ----- ----------- +read I/Os requests number of read I/Os processed +read merges requests number of read I/Os merged with in-queue I/O +read sectors sectors number of sectors read +read ticks milliseconds total wait time for read requests +write I/Os requests number of write I/Os processed +write merges requests number of write I/Os merged with in-queue I/O +write sectors sectors number of sectors written +write ticks milliseconds total wait time for write requests +in_flight requests number of I/Os currently in flight +io_ticks milliseconds total time this block device has been active +time_in_queue milliseconds total wait time for all requests + +read I/Os, write I/Os +===================== + +These values increment when an I/O request completes. + +read merges, write merges +========================= + +These values increment when an I/O request is merged with an +already-queued I/O request. + +read sectors, write sectors +=========================== + +These values count the number of sectors read from or written to this +block device. The "sectors" in question are the standard UNIX 512-byte +sectors, not any device- or filesystem-specific block size. The +counters are incremented when the I/O completes. + +read ticks, write ticks +======================= + +These values count the number of milliseconds that I/O requests have +waited on this block device. If there are multiple I/O requests waiting, +these values will increase at a rate greater than 1000/second; for +example, if 60 read requests wait for an average of 30 ms, the read_ticks +field will increase by 60*30 = 1800. + +in_flight +========= + +This value counts the number of I/O requests that have been issued to +the device driver but have not yet completed. It does not include I/O +requests that are in the queue but not yet issued to the device driver. + +io_ticks +======== + +This value counts the number of milliseconds during which the device has +had I/O requests queued. + +time_in_queue +============= + +This value counts the number of milliseconds that I/O requests have waited +on this block device. If there are multiple I/O requests waiting, this +value will increase as the product of the number of milliseconds times the +number of requests waiting (see "read ticks" above for an example).
Quoted 10 lines · Andy Isaacson
Quoted 9 lines
Documentation/block/stat.txt
Quoted 4 lines
Documentation/block/stat.txt new file +4
-0+in_flight +========= + +This value counts the number of currently-queued I/O requests.A little confusing - it's the number of in flight io at the driver/device end, that is after the block layer. One could read the above as total in flight (total queued in the queue for the device), which is a very different number.
Quoted 2 lines
I wrote from misunderstanding, so it's no suprise what I wrote was wrong. :) Is "number of requests in the queue" available somewhere?
Nope, it's only accounted internally I'm afraid. It's somewhere between 0 and ~ /sys/block/<dev>/queue/nr_requests (it can go a little higher than this value, hence approximately).
Documentation/block/stat.txt line 68
Quoted 8 lines
How does this sound instead of the above?
Documentation/block/stat.txt new file +6
-0+in_flight +========= + +This value counts the number of I/O requests that have been issued to +the device driver but have not yet completed. It does not include I/O +requests that are in the queue but not yet issued to the device driver.
That is perfect, thanks.
Signature · 1 line
Jens Axboe