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
44 input name via the -i option.
45 - The format of the output data can be controlled via the -f or -F
48 options -- 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 -b batch
60 --batch={batch}
61 Standard input read batching
62 -i file
64 --input=file
65 Specifies base name for input files -- default is device.blk‐
66 trace.cpu.
67 As noted above, specifying -i - runs in live mode with blktrace
69 (reading data from standard in).
70 -F typ,fmt
72 --format=typ,fmt
73 -f fmt
74 --format-spec=fmt
75 Sets output format (See OUTPUT DESCRIPTION AND FORMATTING for
76 details.)
77 The -f form specifies a format for all events
79 The -F form allows one to specify a format for a specific event
81 type. The single-character typ field is one of the action speci‐
82 fiers described in ACTION IDENTIFIERS.
83 -M
85 --no-msgs
86 When -d is specified, this will stop messages from being output
87 to the file. (Can seriously reduce the size of the resultant
88 file when using the CFQ I/O scheduler.)
89 -h
91 --hash-by-name
92 Hash processes by name, not by PID
93 -o file
95 --output=file
96 Output file
97 -O
99 --no-text-output
100 Do not produce text output, used for binary (-d) only
101 -d file
103 --dump-binary=file
104 Binary output file
105 -q
107 --quiet
108 Quiet mode
109 -s
111 --per-program-stats
112 Displays data sorted by program
113 -t
115 --track-ios
116 Display time deltas per IO
117 -w span
119 --stopwatch=span
120 Display traces for the span specified -- where span can be:
121 end-time -- Display traces from time 0 through end-time (in ns)
122 or
123 start:end-time -- Display traces from time start through
124 end-time (in ns).
125 -v
127 --verbose
128 More verbose marginal on marginal errors
129 -V
131 --version
132 Display version
133
137 The following trace actions are recognised:
138 C -- complete A previously issued request has been completed. The out‐
141 put will detail the sector and size of that request, as well as the
142 success or failure of it.
143 D -- issued A request that previously resided on the block layer queue
146 or in the i/o scheduler has been sent to the driver.
147 I -- inserted A request is being sent to the i/o scheduler for addition
150 to the internal queue and later service by the driver. The request
151 is fully formed at this time.
152 Q -- queued This notes intent to queue i/o at the given location. No
155 real requests exists yet.
156 B -- bounced The data pages attached to this bio are not reachable by
159 the hardware and must be bounced to a lower memory location. This
160 causes a big slowdown in i/o performance, since the data must be
161 copied to/from kernel buffers. Usually this can be fixed with using
162 better hardware -- either a better i/o controller, or a platform
163 with an IOMMU.
164 M -- back merge A previously inserted request exists that ends on the
167 boundary of where this i/o begins, so the i/o scheduler can merge
168 them together.
169 F -- front merge Same as the back merge, except this i/o ends where a
172 previously inserted requests starts.
173 M --front or back merge One of the above
176 M -- front or back merge One of the above.
179 G -- get request To send any type of request to a block device, a
182 struct request container must be allocated first.
183 S -- sleep No available request structures were available, so the
186 issuer has to wait for one to be freed.
187 P -- plug When i/o is queued to a previously empty block device queue,
190 Linux will plug the queue in anticipation of future ios being added
191 before this data is needed.
192 U -- unplug Some request data already queued in the device, start send‐
195 ing requests to the driver. This may happen automatically if a
196 timeout period has passed (see next entry) or if a number of
197 requests have been added to the queue.
198 T -- unplug due to timer If nobody requests the i/o that was queued
201 after plugging the queue, Linux will automatically unplug it after
202 a defined period has passed.
203 X -- split On raid or device mapper setups, an incoming i/o may strad‐
206 dle a device or internal zone and needs to be chopped up into
207 smaller pieces for service. This may indicate a performance problem
208 due to a bad setup of that raid/dm device, but may also just be
209 part of normal boundary conditions. dm is notably bad at this and
210 will clone lots of i/o.
211 A -- remap For stacked devices, incoming i/o is remapped to device
214 below it in the i/o stack. The remap action details what exactly is
215 being remapped to what.
216
222 The output from blkparse can be tailored for specific use -- in partic‐
223 ular, to ease parsing of output, and/or limit output fields to those
224 the user wants to see. The data for fields which can be output include:
225 a Action, a (small) string (1 or 2 characters) -- see table below for
228 more details
229 c CPU id
232 C Command
235 d RWBS field, a (small) string (1-3 characters) -- see section below
238 for more details
239 D 7-character string containing the major and minor numbers of the
242 event's device (separated by a comma).
243 e Error value
246 m Minor number of event's device.
249 M Major number of event's device.
252 n Number of blocks
255 N Number of bytes
258 p Process ID
261 P Display packet data -- series of hexadecimal values
264 s Sequence numbers
267 S Sector number
270 t Time stamp (nanoseconds)
273 T Time stamp (seconds)
276 u Elapsed value in microseconds (-t command line option)
279 U Payload unsigned integer
282 Note that the user can optionally specify field display width, and
285 optionally a left-aligned specifier. These precede field specifiers,
286 with a '%' character, followed by the optional left-alignment specifier
287 (-) followed by the width (a decimal number) and then the field.
288 Thus, to specify the command in a 12-character field that is left
290 aligned:
291 -f "%-12C"
293
297 The following table shows the various actions which may be output:
298 A IO was remapped to a different device
301 B IO bounced
304 C IO completion
307 D IO issued to driver
310 F IO front merged with request on queue
313 G Get request
316 I IO inserted onto request queue
319 M IO back merged with request on queue
322 P Plug request
325 Q IO handled by request queue code
328 S Sleep request
331 T Unplug due to timeout
334 U Unplug request
337 X Split
340
344 This is a small string containing at least one character ('R' for read,
345 'W' for write, or 'D' for block discard operation), and optionally
346 either a 'B' (for barrier operations) or 'S' (for synchronous opera‐
347 tions).
348
352 The standard header (or initial fields displayed) include:
353 "%D %2c %8s %5T.%9t %5p %2a %3d"
355 Breaking this down:
357 %D Displays the event's device major/minor as: %3d,%-3d.
360 %2c CPU ID (2-character field).
363 %8s Sequence number
366 %5T.%9t
369 5-character field for the seconds portion of the time stamp and
370 a 9-character field for the nanoseconds in the time stamp.
371 %5p 5-character field for the process ID.
374 %2a 2-character field for one of the actions.
377 %3d 3-character field for the RWBS data.
380 Seeing this in action:
382 8,0 3 1 0.000000000 697 G W 223490 + 8
384 [kjournald]
385 The header is the data in this line up to the 223490 (starting
387 block). The default output for all event types includes this
388 header.
389
394 C -- complete
395 If a payload is present, this is presented between parenthesis fol‐
396 lowing the header, followed by the error value.
397 If no payload is present, the sector and number of blocks are pre‐
399 sented (with an intervening plus (+) character). If the -t option
400 was specified, then the elapsed time is presented. In either case,
401 it is followed by the error value for the completion.
402 B -- bounced
404 D -- issued
405 I -- inserted
406 Q -- queued
407 If a payload is present, the number of payload bytes is output,
408 followed by the payload in hexadecimal between parenthesis.
409 If no payload is present, the sector and number of blocks are pre‐
411 sented (with an intervening plus (+) character). If the -t option
412 was specified, then the elapsed time is presented (in parenthesis).
413 In either case, it is followed by the command associated with the
414 event (surrounded by square brackets).
415 F -- front merge
417 G -- get request
418 M -- back merge
419 S -- sleep
420 The starting sector and number of blocks is output (with an inter‐
421 vening plus (+) character), followed by the command associated with
422 the event (surrounded by square brackets).
423 P -- plug
425 The command associated with the event (surrounded by square brack‐
426 ets) is output.
427 U -- unplug
429 T -- unplug due to timer
430 The command associated with the event (surrounded by square brack‐
431 ets) is output, followed by the number of requests outstanding.
432 X -- split
434 The original starting sector followed by the new sector (separated
435 by a slash (/) is output, followed by the command associated with
436 the event (surrounded by square brackets).
437 A -- remap
439 Sector and length is output, along with the original device and
440 sector offset.
441
445 To trace the i/o on the device /dev/hda and parse the output to human
446 readable form, use the following command:
447 % blktrace -d /dev/sda -o - | blkparse -i -
449 (see blktrace (8) for more information). This same behaviour can be
451 achieve with the convenience script btrace. The command
452 % btrace /dev/sda
454 has exactly the same effect as the previous command. See btrace (8) for
456 more information.
457 To trace the i/o on a device and save the output for later processing
459 with blkparse, use blktrace like this:
460 % blktrace /dev/sda /dev/sdb
462 This will trace i/o on the devices /dev/sda and /dev/sdb and save the
464 recorded information in the files sda and sdb in the current directory,
465 for the two different devices, respectively. This trace information
466 can later be parsed by the blkparse utility:
467 % blkparse sda sdb
469 which will output the previously recorded tracing information in human
471 readable form to stdout.
472
476 blkparse was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.
477 This man page was created from the blktrace documentation by Bas
478 Zoetekouw.
479
483 Report bugs to <linux-btrace@vger.kernel.org>
484
487 Copyright © 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
488 This is free software. You may redistribute copies of it under the
489 terms of the GNU General Public License
490 <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the
491 extent permitted by law.
492 This manual page was created for Debian by Bas Zoetekouw. It was
493 derived from the documentation provided by the authors and it may be
494 used, distributed and modified under the terms of the GNU General Pub‐
495 lic License, version 2.
496 On Debian systems, the text of the GNU General Public License can be
497 found in /usr/share/common-licenses/GPL-2.
498
501 btrace (8), blktrace (8), verify_blkparse (1), blkrawverify (1), btt
502 (1)
503blktrace git-20070306202522 March 6, 2007 BLKPARSE(1)