1 .TH BLKPARSE 1 "March 6, 2007" "blktrace git\-20070306202522" ""
5 blkparse \- produce formatted output of event streams of block devices
9 .B blkparse [ \fIoptions\fR ]
14 The \fIblkparse\fR utility will attempt to combine streams of events for
15 various devices on various CPUs, and produce a formatted output of the event
16 information. Specifically, it will take the (machine-readable) output of the
17 \fIblktrace\fR utility and convert it to a nicely formatted and human-readable
20 As with \fIblktrace\fR, some details concerning \fIblkparse\fR
21 will help in understanding the command line options presented below.
26 By default, \fIblkparse\fR expects to run in a post-processing mode; one where
27 the trace events have been saved by a previous run of blktrace, and blkparse
28 is combining event streams and dumping formatted data.
30 blkparse may be run in a live manner concurrently with blktrace by specifying
31 \fB\-i \-\fR to blkparse, and combining it with the live option for blktrace.
34 % blktrace \-d /dev/sda \-o \- | blkparse \-i \-
38 You can set how many blkparse batches event reads via the \fB\-b\fR option, the
39 default is to handle events in batches of 512.
43 If you have saved event traces in blktrace with different output names (via
44 the \fB\-o\fR option to blktrace), you must specify the same input name via the
49 The format of the output data can be controlled via the \fB\-f\fR or \fB\-F\fR
50 options \-\- see OUTPUT DESCRIPTION AND FORMATTING for details.
53 By default, blkparse sends formatted data to standard output. This may
54 be changed via the \fB\-o\fR option, or text output can be disabled via the
55 \fB\-O\fR option. A merged binary stream can be produced using the \fB\-d\fR
63 \-\-set-mask=\fIhex-mask\fR
65 Set filter mask to \fIhex-mask\fR, see blktrace (8) for masks
70 \-\-act-mask=\fImask\fR
72 Add \fImask\fR to current filter, see blktrace (8) for masks
77 \-\-input-directory=\fIdir\fR
79 Prepend \fIdir\fR to input file names
86 Standard input read batching
93 Specifies base name for input files \-\- default is \fIdevice\fR.blktrace.\fIcpu\fR.
95 As noted above, specifying \fB\-i \-\fR runs in live mode with blktrace
96 (reading data from standard in).
101 \-\-format=\fItyp,fmt\fR
105 \-\-format\-spec=\fIfmt\fR
108 (See OUTPUT DESCRIPTION AND FORMATTING for details.)
110 The \-f form specifies a format for all events
112 The \-F form allows one to specify a format for a specific
113 event type. The single\-character \fItyp\fR field is one of the
114 action specifiers described in ACTION IDENTIFIERS.
121 When \-d is specified, this will stop messages from being output to the
122 file. (Can seriously reduce the size of the resultant file when using
123 the CFQ I/O scheduler.)
130 Hash processes by name, not by PID
135 \-\-output=\fIfile\fR
144 Do \fInot\fR produce text output, used for binary (\fB\-d\fR) only
149 \-\-dump\-binary=\fIfile\fR
163 \-\-per\-program\-stats
165 Displays data sorted by program
170 \-\-sort\-program\-stats=\fIevent\fR
173 Displays each program's data sorted by program name or io event, like
174 Queued, Read, Write and Complete. When \-S is specified the \-s will be ignored.
175 The capital letters Q,R,W,C stand for KB, then q/r/w/c stand for IO.
177 If you want to soct programs by how many data they queued, you can use:
179 blkparse -i sda.blktrace. -q \-S Q \-o sda.parse
187 Display time deltas per IO
192 \-\-stopwatch=\fIspan\fR
194 Display traces for the \fIspan\fR specified \-\- where span can be:
196 \fIend\-time\fR \-\- Display traces from time 0 through \fIend\-time\fR (in ns)
200 \fIstart:end\-time\fR \-\- Display traces from time \fIstart\fR
201 through end\-time (in ns).
208 More verbose marginal on marginal errors
220 The following trace actions are recognised:
224 A previously issued request has been completed. The output will detail the
225 sector and size of that request, as well as the success or failure of it.
229 A request that previously resided on the block layer queue or in the i/o
230 scheduler has been sent to the driver.
234 A request is being sent to the i/o scheduler for addition to the internal queue
235 and later service by the driver. The request is fully formed at this time.
239 This notes intent to queue i/o at the given location. No real requests exists
244 The data pages attached to this \fIbio\fR are not reachable by the hardware
245 and must be bounced to a lower memory location. This causes a big slowdown in
246 i/o performance, since the data must be copied to/from kernel buffers. Usually
247 this can be fixed with using better hardware -- either a better i/o controller,
248 or a platform with an IOMMU.
251 \fBM -- back merge\fR
252 A previously inserted request exists that ends on the boundary of where this i/o
253 begins, so the i/o scheduler can merge them together.
256 \fBF -- front merge\fR
257 Same as the back merge, except this i/o ends where a previously inserted
261 \fBM -- front or back merge\fR
265 \fBG -- get request\fR
266 To send any type of request to a block device, a \fIstruct request\fR
267 container must be allocated first.
271 No available request structures were available, so the issuer has to wait for
276 When i/o is queued to a previously empty block device queue, Linux will plug the
277 queue in anticipation of future ios being added before this data is needed.
281 Some request data already queued in the device, start sending requests to the
282 driver. This may happen automatically if a timeout period has passed (see next
283 entry) or if a number of requests have been added to the queue.
286 \fBT -- unplug due to timer\fR
287 If nobody requests the i/o that was queued after plugging the queue, Linux will
288 automatically unplug it after a defined period has passed.
292 On raid or device mapper setups, an incoming i/o may straddle a device or
293 internal zone and needs to be chopped up into smaller pieces for service. This
294 may indicate a performance problem due to a bad setup of that raid/dm device,
295 but may also just be part of normal boundary conditions. dm is notably bad at
296 this and will clone lots of i/o.
300 For stacked devices, incoming i/o is remapped to device below it in the i/o
301 stack. The remap action details what exactly is being remapped to what.
305 Put a request back on queue.
310 .SH "OUTPUT DESCRIPTION AND FORMATTING"
312 The output from blkparse can be tailored for specific use -- in particular, to ease
313 parsing of output, and/or limit output fields to those the user wants to see. The
314 data for fields which can be output include:
317 Action, a (small) string (1 or 2 characters) -- see table below for more details
326 RWBS field, a (small) string (1-3 characters) -- see section below for more details
329 7-character string containing the major and minor numbers of
330 the event's device (separated by a comma).
336 Cgroup identifier of the cgroup that generated the IO. Note that this requires
337 appropriate kernel support (kernel version at least 4.14).
340 Minor number of event's device.
343 Major number of event's device.
355 Display packet data \-\- series of hexadecimal values
364 Time stamp (nanoseconds)
370 Elapsed value in microseconds (\fI\-t\fR command line option)
373 Payload unsigned integer
376 The absolute time, as local time in your time zone, with no date displayed
379 Note that the user can optionally specify field display width, and optionally a
380 left-aligned specifier. These precede field specifiers, with a '%' character,
381 followed by the optional left-alignment specifier (\-) followed by the width (a
382 decimal number) and then the field.
384 Thus, to specify the command in a 12-character field that is left aligned:
389 .SH "ACTION IDENTIFIERS"
391 The following table shows the various actions which may be output:
394 IO was remapped to a different device
406 IO front merged with request on queue
412 IO inserted onto request queue
415 IO back merged with request on queue
421 IO handled by request queue code
427 Unplug due to timeout
436 .SH "RWBS DESCRIPTION"
438 This is a small string containing at least one character ('R' for read, 'W'
439 for write, or 'D' for block discard operation), and optionally either
440 a 'B' (for barrier operations) or 'S' (for synchronous operations).
445 The standard header (or initial fields displayed) include:
447 "%D %2c %8s %5T.%9t %5p %2a %3d"
452 Displays the event's device major/minor as: %3d,%\-3d.
455 CPU ID (2-character field).
461 5-character field for the seconds portion of the time stamp and a 9-character field for the nanoseconds in the time stamp.
464 5-character field for the process ID.
467 2-character field for one of the actions.
470 3-character field for the RWBS data.
472 Seeing this in action:
474 8,0 3 1 0.000000000 697 G W 223490 + 8 [kjournald]
476 The header is the data in this line up to the 223490 (starting block).
477 The default output for all event types includes this header.
481 .SH "DEFAULT OUTPUT PER ACTION"
483 \fBC \-\- complete\fR
485 If a payload is present, this is presented between
486 parenthesis following the header, followed by the error value.
488 If no payload is present, the sector and number of blocks are presented
489 (with an intervening plus (+) character). If the \fB\-t\fR option
490 was specified, then the elapsed time is presented. In either case,
491 it is followed by the error value for the completion.
498 \fBI \-\- inserted\fR
502 If a payload is present, the number of payload bytes
503 is output, followed by the payload in hexadecimal between parenthesis.
505 If no payload is present, the sector and number of blocks are presented
506 (with an intervening plus (+) character). If the \fB\-t\fR option was
507 specified, then the elapsed time is presented (in parenthesis). In
508 either case, it is followed by the command associated with the event
509 (surrounded by square brackets).
512 \fBF \-\- front merge\fR
514 \fBG \-\- get request\fR
516 \fBM \-\- back merge\fR
520 The starting sector and number of blocks is output
521 (with an intervening plus (+) character), followed by the command
522 associated with the event (surrounded by square brackets).
527 The command associated with the event (surrounded by
528 square brackets) is output.
533 \fBT \-\- unplug due to timer\fR
535 The command associated with the event
536 (surrounded by square brackets) is output, followed by the number of
537 requests outstanding.
542 The original starting sector followed by the new
543 sector (separated by a slash (/) is output, followed by the command
544 associated with the event (surrounded by square brackets).
549 Sector and length is output, along with the original
550 device and sector offset.
555 To trace the i/o on the device \fI/dev/sda\fB and parse the output to human
556 readable form, use the following command:
558 % blktrace \-d /dev/sda \-o \- | blkparse \-i \-
560 (see \fIblktrace\fR (8) for more information).
561 This same behaviour can be achieve with the convenience script \fIbtrace\fR.
566 has exactly the same effect as the previous command. See \fIbtrace\fR (8) for
569 To trace the i/o on a device and save the output for later processing with
570 \fIblkparse\fR, use \fIblktrace\fR like this:
572 % blktrace /dev/sda /dev/sdb
574 This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save
575 the recorded information in the files \fIsda\fR and \fIsdb\fR in the current
576 directory, for the two different devices, respectively. This trace
577 information can later be parsed by the \fIblkparse\fR utility:
581 which will output the previously recorded tracing information in human
582 readable form to stdout.
586 \fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This
587 man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw.
591 Report bugs to <linux\-btrace@vger.kernel.org>
594 Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
596 This is free software. You may redistribute copies of it under the terms of
597 the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
598 There is NO WARRANTY, to the extent permitted by law.
600 This manual page was created for Debian by Bas Zoetekouw. It was derived from
601 the documentation provided by the authors and it may be used, distributed and
602 modified under the terms of the GNU General Public License, version 2.
604 On Debian systems, the text of the GNU General Public License can be found in
605 /usr/share/common\-licenses/GPL\-2.
608 btrace (8), blktrace (8), verify_blkparse (1), blkrawverify (1), btt (1)