| BLKPARSE(1) | BLKPARSE(1) |
blkparse - produce formatted output of event streams of block devices
blkparse [ options ]
The blkparse utility will attempt to combine streams of events for various devices on various CPUs, and produce a formatted output of the event information. Specifically, it will take the (machine-readable) output of the blktrace utility and convert it to a nicely formatted and human-readable form.
As with blktrace, some details concerning blkparse will help in understanding the command line options presented below.
blkparse may be run in a live manner concurrently with blktrace by specifying -i - to blkparse, and combining it with the live option for blktrace. An example would be:
% blktrace -d /dev/sda -o - | blkparse -i -
By default, blkparse sends formatted data to standard output. This may be changed via the -o option, or text output can be disabled via the -O option. A merged binary stream can be produced using the -d option.
-A hex-mask
--set-mask=hex-mask
-a mask
--act-mask=mask
-D dir
--input-directory=dir
-b batch
--batch={batch}
-i file
--input=file
As noted above, specifying -i - runs in live mode with blktrace (reading data from standard in).
-F typ,fmt
--format=typ,fmt
-f fmt
--format-spec=fmt
The -f form specifies a format for all events
The -F form allows one to specify a format for a specific event type. The single-character typ field is one of the action specifiers described in ACTION IDENTIFIERS.
-M
--no-msgs
-h
--hash-by-name
-o file
--output=file
-O
--no-text-output
-d file
--dump-binary=file
-q
--quiet
-s
--per-program-stats
-t
--track-ios
-w span
--stopwatch=span
-v
--verbose
-V
--version
The following trace actions are recognised:
C -- complete A previously issued request has been completed. The output will detail the sector and size of that request, as well as the success or failure of it.
D -- issued A request that previously resided on the block layer queue or in the i/o scheduler has been sent to the driver.
I -- inserted A request is being sent to the i/o scheduler for addition to the internal queue and later service by the driver. The request is fully formed at this time.
Q -- queued This notes intent to queue i/o at the given location. No real requests exists yet.
B -- bounced The data pages attached to this bio are not reachable by the hardware and must be bounced to a lower memory location. This causes a big slowdown in i/o performance, since the data must be copied to/from kernel buffers. Usually this can be fixed with using better hardware -- either a better i/o controller, or a platform with an IOMMU.
M -- back merge A previously inserted request exists that ends on the boundary of where this i/o begins, so the i/o scheduler can merge them together.
F -- front merge Same as the back merge, except this i/o ends where a previously inserted requests starts.
M -- front or back merge One of the above
M -- front or back merge One of the above.
G -- get request To send any type of request to a block device, a struct request container must be allocated first.
S -- sleep No available request structures were available, so the issuer has to wait for one to be freed.
P -- plug When i/o is queued to a previously empty block device queue, Linux will plug the queue in anticipation of future ios being added before this data is needed.
U -- unplug Some request data already queued in the device, start sending requests to the driver. This may happen automatically if a timeout period has passed (see next entry) or if a number of requests have been added to the queue.
T -- unplug due to timer If nobody requests the i/o that was queued after plugging the queue, Linux will automatically unplug it after a defined period has passed.
X -- split On raid or device mapper setups, an incoming i/o may straddle a device or internal zone and needs to be chopped up into smaller pieces for service. This may indicate a performance problem due to a bad setup of that raid/dm device, but may also just be part of normal boundary conditions. dm is notably bad at this and will clone lots of i/o.
A -- remap For stacked devices, incoming i/o is remapped to device below it in the i/o stack. The remap action details what exactly is being remapped to what.
The output from blkparse can be tailored for specific use -- in particular, to ease parsing of output, and/or limit output fields to those the user wants to see. The data for fields which can be output include:
Note that the user can optionally specify field display width, and optionally a left-aligned specifier. These precede field specifiers, with a '%' character, followed by the optional left-alignment specifier (-) followed by the width (a decimal number) and then the field.
Thus, to specify the command in a 12-character field that is left aligned:
-f "%-12C"
The following table shows the various actions which may be output:
This is a small string containing at least one character ('R' for read, 'W' for write, or 'D' for block discard operation), and optionally either a 'B' (for barrier operations) or 'S' (for synchronous operations).
The standard header (or initial fields displayed) include:
"%D %2c %8s %5T.%9t %5p %2a %3d"
Breaking this down:
Seeing this in action:
8,0 3 1 0.000000000 697 G W 223490 + 8 [kjournald]
The header is the data in this line up to the 223490 (starting block). The default output for all event types includes this header.
C -- complete
If no payload is present, the sector and number of blocks are presented (with an intervening plus (+) character). If the -t option was specified, then the elapsed time is presented. In either case, it is followed by the error value for the completion.
B -- bounced
D -- issued
I -- inserted
Q -- queued
If no payload is present, the sector and number of blocks are presented (with an intervening plus (+) character). If the -t option was specified, then the elapsed time is presented (in parenthesis). In either case, it is followed by the command associated with the event (surrounded by square brackets).
F -- front merge
G -- get request
M -- back merge
S -- sleep
P -- plug
U -- unplug
T -- unplug due to timer
X -- split
A -- remap
To trace the i/o on the device /dev/sda and parse the output to human readable form, use the following command:
% blktrace -d /dev/sda -o - | blkparse -i -
(see blktrace (8) for more information). This same behaviour can be achieve with the convenience script btrace. The command
% btrace /dev/sda
has exactly the same effect as the previous command. See btrace (8) for more information.
To trace the i/o on a device and save the output for later processing with blkparse, use blktrace like this:
% blktrace /dev/sda /dev/sdb
This will trace i/o on the devices /dev/sda and /dev/sdb and save the recorded information in the files sda and sdb in the current directory, for the two different devices, respectively. This trace information can later be parsed by the blkparse utility:
% blkparse sda sdb
which will output the previously recorded tracing information in human readable form to stdout.
blkparse was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This man page was created from the blktrace documentation by Bas Zoetekouw.
Report bugs to <linux-btrace@vger.kernel.org>
Copyright © 2006 Jens Axboe, Alan D. Brunelle and Nathan
Scott.
This is free software. You may redistribute copies of it under the terms of
the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
There is NO WARRANTY, to the extent permitted by law.
This manual page was created for Debian by Bas Zoetekouw. It was derived from
the documentation provided by the authors and it may be used, distributed
and modified under the terms of the GNU General Public License, version 2.
On Debian systems, the text of the GNU General Public License can be found in
/usr/share/common-licenses/GPL-2.
btrace (8), blktrace (8), verify_blkparse (1), blkrawverify (1), btt (1)
| March 6, 2007 | blktrace git-20070306202522 |