1BLKPARSE(1) BLKPARSE(1)
2
6 blkparse - produce formatted output of event streams of block devices
7
11 blkparse [ options ]
12
16 The blkparse utility will attempt to combine streams of events for var‐
17 ious devices on various CPUs, and produce a formatted output of the
18 event information. Specifically, it will take the (machine-readable)
19 output of the blktrace utility and convert it to a nicely formatted and
20 human-readable form.
21 As with blktrace, some details concerning blkparse will help in under‐
23 standing the command line options presented below.
24 - By default, blkparse expects to run in a post-processing mode; one
28 where the trace events have been saved by a previous run of blktrace,
29 and blkparse is combining event streams and dumping formatted data.
30 blkparse may be run in a live manner concurrently with blktrace by
32 specifying -i - to blkparse, and combining it with the live option
33 for blktrace. An example would be:
34 % blktrace -d /dev/sda -o - | blkparse -i -
36 - You can set how many blkparse batches event reads via the -b option,
39 the default is to handle events in batches of 512.
40 - If you have saved event traces in blktrace with different output
43 names (via the -o option to blktrace), you must specify the same in‐
44 put name via the -i option.
45 - The format of the output data can be controlled via the -f or -F op‐
48 tions -- see OUTPUT DESCRIPTION AND FORMATTING for details.
49 By default, blkparse sends formatted data to standard output. This may
52 be changed via the -o option, or text output can be disabled via the -O
53 option. A merged binary stream can be produced using the -d option.
54
59 -A hex-mask
60 --set-mask=hex-mask
61 Set filter mask to hex-mask, see blktrace (8) for masks
62 -a mask
64 --act-mask=mask
65 Add mask to current filter, see blktrace (8) for masks
66 -D dir
68 --input-directory=dir
69 Prepend dir to input file names
70 -b batch
72 --batch={batch}
73 Standard input read batching
74 -i file
76 --input=file
77 Specifies base name for input files -- default is device.blk‐
78 trace.cpu.
79 As noted above, specifying -i - runs in live mode with blktrace
81 (reading data from standard in).
82 -F typ,fmt
84 --format=typ,fmt
85 -f fmt
86 --format-spec=fmt
87 Sets output format (See OUTPUT DESCRIPTION AND FORMATTING for
88 details.)
89 The -f form specifies a format for all events
91 The -F form allows one to specify a format for a specific event
93 type. The single-character typ field is one of the action speci‐
94 fiers described in ACTION IDENTIFIERS.
95 -M
97 --no-msgs
98 When -d is specified, this will stop messages from being output
99 to the file. (Can seriously reduce the size of the resultant
100 file when using the CFQ I/O scheduler.)
101 -h
103 --hash-by-name
104 Hash processes by name, not by PID
105 -o file
107 --output=file
108 Output file
109 -O
111 --no-text-output
112 Do not produce text output, used for binary (-d) only
113 -d file
115 --dump-binary=file
116 Binary output file
117 -q
119 --quiet
120 Quiet mode
121 -s
123 --per-program-stats
124 Displays data sorted by program
125 -S event
127 --sort-program-stats=event
128 Displays each program's data sorted by program name or io event,
129 like Queued, Read, Write and Complete. When -S is specified the
130 -s will be ignored. The capital letters Q,R,W,C stand for KB,
131 then q/r/w/c stand for IO.
132 If you want to soct programs by how many data they queued, you
134 can use:
135 blkparse -i sda.blktrace. -q -S Q -o sda.parse
137 -t
140 --track-ios
141 Display time deltas per IO
142 -w span
144 --stopwatch=span
145 Display traces for the span specified -- where span can be:
146 end-time -- Display traces from time 0 through end-time (in ns)
147 or
148 start:end-time -- Display traces from time start through
149 end-time (in ns).
150 -v
152 --verbose
153 More verbose marginal on marginal errors
154 -V
156 --version
157 Display version
158
162 The following trace actions are recognised:
163 C -- complete A previously issued request has been completed. The out‐
166 put will detail the sector and size of that request, as well as the
167 success or failure of it.
168 D -- issued A request that previously resided on the block layer queue
171 or in the i/o scheduler has been sent to the driver.
172 I -- inserted A request is being sent to the i/o scheduler for addition
175 to the internal queue and later service by the driver. The request
176 is fully formed at this time.
177 Q -- queued This notes intent to queue i/o at the given location. No
180 real requests exists yet.
181 B -- bounced The data pages attached to this bio are not reachable by
184 the hardware and must be bounced to a lower memory location. This
185 causes a big slowdown in i/o performance, since the data must be
186 copied to/from kernel buffers. Usually this can be fixed with using
187 better hardware -- either a better i/o controller, or a platform
188 with an IOMMU.
189 M -- back merge A previously inserted request exists that ends on the
192 boundary of where this i/o begins, so the i/o scheduler can merge
193 them together.
194 F -- front merge Same as the back merge, except this i/o ends where a
197 previously inserted requests starts.
198 M -- front or back merge One of the above.
201 G -- get request To send any type of request to a block device, a
204 struct request container must be allocated first.
205 S -- sleep No available request structures were available, so the is‐
208 suer has to wait for one to be freed.
209 P -- plug When i/o is queued to a previously empty block device queue,
212 Linux will plug the queue in anticipation of future ios being added
213 before this data is needed.
214 U -- unplug Some request data already queued in the device, start send‐
217 ing requests to the driver. This may happen automatically if a
218 timeout period has passed (see next entry) or if a number of re‐
219 quests have been added to the queue.
220 T -- unplug due to timer If nobody requests the i/o that was queued af‐
223 ter plugging the queue, Linux will automatically unplug it after a
224 defined period has passed.
225 X -- split On raid or device mapper setups, an incoming i/o may strad‐
228 dle a device or internal zone and needs to be chopped up into
229 smaller pieces for service. This may indicate a performance problem
230 due to a bad setup of that raid/dm device, but may also just be
231 part of normal boundary conditions. dm is notably bad at this and
232 will clone lots of i/o.
233 A -- remap For stacked devices, incoming i/o is remapped to device be‐
236 low it in the i/o stack. The remap action details what exactly is
237 being remapped to what.
238 R -- requeue Put a request back on queue.
241
247 The output from blkparse can be tailored for specific use -- in partic‐
248 ular, to ease parsing of output, and/or limit output fields to those
249 the user wants to see. The data for fields which can be output include:
250 a Action, a (small) string (1 or 2 characters) -- see table below for
253 more details
254 c CPU id
257 C Command
260 d RWBS field, a (small) string (1-3 characters) -- see section below
263 for more details
264 D 7-character string containing the major and minor numbers of the
267 event's device (separated by a comma).
268 e Error value
271 g Cgroup identifier of the cgroup that generated the IO. Note that
274 this requires appropriate kernel support (kernel version at least
275 4.14).
276 m Minor number of event's device.
279 M Major number of event's device.
282 n Number of blocks
285 N Number of bytes
288 p Process ID
291 P Display packet data -- series of hexadecimal values
294 s Sequence numbers
297 S Sector number
300 t Time stamp (nanoseconds)
303 T Time stamp (seconds)
306 u Elapsed value in microseconds (-t command line option)
309 U Payload unsigned integer
312 z The absolute time, as local time in your time zone, with no date
315 displayed
316 Note that the user can optionally specify field display width, and op‐
319 tionally a left-aligned specifier. These precede field specifiers, with
320 a '%' character, followed by the optional left-alignment specifier (-)
321 followed by the width (a decimal number) and then the field.
322 Thus, to specify the command in a 12-character field that is left
324 aligned:
325 -f "%-12C"
327
331 The following table shows the various actions which may be output:
332 A IO was remapped to a different device
335 B IO bounced
338 C IO completion
341 D IO issued to driver
344 F IO front merged with request on queue
347 G Get request
350 I IO inserted onto request queue
353 M IO back merged with request on queue
356 P Plug request
359 Q IO handled by request queue code
362 S Sleep request
365 T Unplug due to timeout
368 U Unplug request
371 X Split
374
378 This is a small string containing at least one character ('R' for read,
379 'W' for write, or 'D' for block discard operation), and optionally ei‐
380 ther a 'B' (for barrier operations) or 'S' (for synchronous opera‐
381 tions).
382
386 The standard header (or initial fields displayed) include:
387 "%D %2c %8s %5T.%9t %5p %2a %3d"
389 Breaking this down:
391 %D Displays the event's device major/minor as: %3d,%-3d.
394 %2c CPU ID (2-character field).
397 %8s Sequence number
400 %5T.%9t
403 5-character field for the seconds portion of the time stamp and
404 a 9-character field for the nanoseconds in the time stamp.
405 %5p 5-character field for the process ID.
408 %2a 2-character field for one of the actions.
411 %3d 3-character field for the RWBS data.
414 Seeing this in action:
416 8,0 3 1 0.000000000 697 G W 223490 + 8
418 [kjournald]
419 The header is the data in this line up to the 223490 (starting
421 block). The default output for all event types includes this
422 header.
423
428 C -- complete
429 If a payload is present, this is presented between parenthesis fol‐
430 lowing the header, followed by the error value.
431 If no payload is present, the sector and number of blocks are pre‐
433 sented (with an intervening plus (+) character). If the -t option
434 was specified, then the elapsed time is presented. In either case,
435 it is followed by the error value for the completion.
436 B -- bounced
438 D -- issued
439 I -- inserted
440 Q -- queued
441 If a payload is present, the number of payload bytes is output,
442 followed by the payload in hexadecimal between parenthesis.
443 If no payload is present, the sector and number of blocks are pre‐
445 sented (with an intervening plus (+) character). If the -t option
446 was specified, then the elapsed time is presented (in parenthesis).
447 In either case, it is followed by the command associated with the
448 event (surrounded by square brackets).
449 F -- front merge
451 G -- get request
452 M -- back merge
453 S -- sleep
454 The starting sector and number of blocks is output (with an inter‐
455 vening plus (+) character), followed by the command associated with
456 the event (surrounded by square brackets).
457 P -- plug
459 The command associated with the event (surrounded by square brack‐
460 ets) is output.
461 U -- unplug
463 T -- unplug due to timer
464 The command associated with the event (surrounded by square brack‐
465 ets) is output, followed by the number of requests outstanding.
466 X -- split
468 The original starting sector followed by the new sector (separated
469 by a slash (/) is output, followed by the command associated with
470 the event (surrounded by square brackets).
471 A -- remap
473 Sector and length is output, along with the original device and
474 sector offset.
475
479 To trace the i/o on the device /dev/sda and parse the output to human
480 readable form, use the following command:
481 % blktrace -d /dev/sda -o - | blkparse -i -
483 (see [22mblktrace (8) for more information). This same behaviour can be
485 achieve with the convenience script btrace. The command
486 % btrace /dev/sda
488 has exactly the same effect as the previous command. See btrace (8) for
490 more information.
491 To trace the i/o on a device and save the output for later processing
493 with blkparse, use blktrace like this:
494 % blktrace /dev/sda /dev/sdb
496 This will trace i/o on the devices /dev/sda and /dev/sdb and save the
498 recorded information in the files sda and sdb in the current directory,
499 for the two different devices, respectively. This trace information
500 can later be parsed by the blkparse utility:
501 % blkparse sda sdb
503 which will output the previously recorded tracing information in human
505 readable form to stdout.
506
510 blkparse was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.
511 This man page was created from the blktrace documentation by Bas
512 Zoetekouw.
513
517 Report bugs to <linux-btrace@vger.kernel.org>
518
521 Copyright © 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
522 This is free software. You may redistribute copies of it under the
523 terms of the GNU General Public License <http://www.gnu.org/li‐
524 censes/gpl.html>. There is NO WARRANTY, to the extent permitted by
525 law.
526 This manual page was created for Debian by Bas Zoetekouw. It was de‐
527 rived from the documentation provided by the authors and it may be
528 used, distributed and modified under the terms of the GNU General Pub‐
529 lic License, version 2.
530 On Debian systems, the text of the GNU General Public License can be
531 found in /usr/share/common-licenses/GPL-2.
532
535 btrace (8), blktrace (8), verify_blkparse (1), blkrawverify (1), btt
536 (1)
537blktrace git-20070306202522 March 6, 2007 BLKPARSE(1)