1BLKPARSE(1)                                                        BLKPARSE(1)
2
3
4

NAME

6       blkparse - produce formatted output of event streams of block devices
7
8
9

SYNOPSIS

11       blkparse [ options ]
12
13
14

DESCRIPTION

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
22       As  with blktrace, some details concerning blkparse will help in under‐
23       standing the command line options presented below.
24
25
26
27       - 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
31         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
35            % blktrace -d /dev/sda -o - | blkparse -i -
36
37
38       - 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
41
42       - 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
46
47       - The  format  of  the  output  data can be controlled via the -f or -F
48         options -- see OUTPUT DESCRIPTION AND FORMATTING for details.
49
50
51       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
55
56
57

OPTIONS

59       -A hex-mask
60       --set-mask=hex-mask
61              Set filter mask to hex-mask, see blktrace (8) for masks
62
63       -a mask
64       --act-mask=mask
65              Add mask to current filter, see blktrace (8) for masks
66
67       -D dir
68       --input-directory=dir
69              Prepend dir to input file names
70
71       -b batch
72       --batch={batch}
73              Standard input read batching
74
75       -i file
76       --input=file
77              Specifies base name for input files --  default  is  device.blk‐
78              trace.cpu.
79
80              As  noted above, specifying -i - runs in live mode with blktrace
81              (reading data from standard in).
82
83       -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
90              The -f form specifies a format for all events
91
92              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
96       -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
102       -h
103       --hash-by-name
104              Hash processes by name, not by PID
105
106       -o file
107       --output=file
108              Output file
109
110       -O
111       --no-text-output
112              Do not produce text output, used for binary (-d) only
113
114       -d file
115       --dump-binary=file
116              Binary output file
117
118       -q
119       --quiet
120              Quiet mode
121
122       -s
123       --per-program-stats
124              Displays data sorted by program
125
126       -t
127       --track-ios
128              Display time deltas per IO
129
130       -w span
131       --stopwatch=span
132              Display traces for the span specified -- where span can be:
133              end-time -- Display traces from time 0 through end-time (in ns)
134              or
135              start:end-time   --  Display  traces  from  time  start  through
136              end-time (in ns).
137
138       -v
139       --verbose
140              More verbose marginal on marginal errors
141
142       -V
143       --version
144              Display version
145
146
147

TRACE ACTIONS

149       The following trace actions are recognised:
150
151
152       C -- complete A previously issued request has been completed.  The out‐
153           put will detail the sector and size of that request, as well as the
154           success or failure of it.
155
156
157       D -- issued A request that previously resided on the block layer  queue
158           or in the i/o scheduler has been sent to the driver.
159
160
161       I -- inserted A request is being sent to the i/o scheduler for addition
162           to the internal queue and later service by the driver. The  request
163           is fully formed at this time.
164
165
166       Q  --  queued This notes intent to queue i/o at the given location.  No
167           real requests exists yet.
168
169
170       B -- bounced The data pages attached to this bio are not  reachable  by
171           the  hardware  and must be bounced to a lower memory location. This
172           causes a big slowdown in i/o performance, since the  data  must  be
173           copied to/from kernel buffers. Usually this can be fixed with using
174           better hardware -- either a better i/o controller,  or  a  platform
175           with an IOMMU.
176
177
178       M  --  back merge A previously inserted request exists that ends on the
179           boundary of where this i/o begins, so the i/o scheduler  can  merge
180           them together.
181
182
183       F  --  front merge Same as the back merge, except this i/o ends where a
184           previously inserted requests starts.
185
186
187       M --front or back merge One of the above
188
189
190       M -- front or back merge One of the above.
191
192
193       G -- get request To send any type of  request  to  a  block  device,  a
194           struct request container must be allocated first.
195
196
197       S  --  sleep  No  available  request  structures were available, so the
198           issuer has to wait for one to be freed.
199
200
201       P -- plug When i/o is queued to a previously empty block device  queue,
202           Linux will plug the queue in anticipation of future ios being added
203           before this data is needed.
204
205
206       U -- unplug Some request data already queued in the device, start send‐
207           ing  requests  to  the  driver.  This may happen automatically if a
208           timeout period has passed (see  next  entry)  or  if  a  number  of
209           requests have been added to the queue.
210
211
212       T  --  unplug  due  to timer If nobody requests the i/o that was queued
213           after plugging the queue, Linux will automatically unplug it  after
214           a defined period has passed.
215
216
217       X  -- split On raid or device mapper setups, an incoming i/o may strad‐
218           dle a device or internal zone and  needs  to  be  chopped  up  into
219           smaller pieces for service. This may indicate a performance problem
220           due to a bad setup of that raid/dm device, but  may  also  just  be
221           part  of  normal boundary conditions. dm is notably bad at this and
222           will clone lots of i/o.
223
224
225       A -- remap For stacked devices, incoming  i/o  is  remapped  to  device
226           below it in the i/o stack. The remap action details what exactly is
227           being remapped to what.
228
229
230
231
232

OUTPUT DESCRIPTION AND FORMATTING

234       The output from blkparse can be tailored for specific use -- in partic‐
235       ular,  to  ease  parsing of output, and/or limit output fields to those
236       the user wants to see. The data for fields which can be output include:
237
238
239       a   Action, a (small) string (1 or 2 characters) -- see table below for
240           more details
241
242
243       c   CPU id
244
245
246       C   Command
247
248
249       d   RWBS field, a (small) string (1-3 characters)  -- see section below
250           for more details
251
252
253       D   7-character string containing the major and minor  numbers  of  the
254           event's device (separated by a comma).
255
256
257       e   Error value
258
259
260       m   Minor number of event's device.
261
262
263       M   Major number of event's device.
264
265
266       n   Number of blocks
267
268
269       N   Number of bytes
270
271
272       p   Process ID
273
274
275       P   Display packet data -- series of hexadecimal values
276
277
278       s   Sequence numbers
279
280
281       S   Sector number
282
283
284       t   Time stamp (nanoseconds)
285
286
287       T   Time stamp (seconds)
288
289
290       u   Elapsed value in microseconds (-t command line option)
291
292
293       U   Payload unsigned integer
294
295
296       Note  that  the  user  can  optionally specify field display width, and
297       optionally a left-aligned specifier. These  precede  field  specifiers,
298       with a '%' character, followed by the optional left-alignment specifier
299       (-) followed by the width (a decimal number) and then the field.
300
301       Thus, to specify the command in  a  12-character  field  that  is  left
302       aligned:
303
304           -f "%-12C"
305
306
307

ACTION IDENTIFIERS

309       The following table shows the various actions which may be output:
310
311
312       A      IO was remapped to a different device
313
314
315       B      IO bounced
316
317
318       C      IO completion
319
320
321       D      IO issued to driver
322
323
324       F      IO front merged with request on queue
325
326
327       G      Get request
328
329
330       I      IO inserted onto request queue
331
332
333       M      IO back merged with request on queue
334
335
336       P      Plug request
337
338
339       Q      IO handled by request queue code
340
341
342       S      Sleep request
343
344
345       T      Unplug due to timeout
346
347
348       U      Unplug request
349
350
351       X      Split
352
353
354

RWBS DESCRIPTION

356       This is a small string containing at least one character ('R' for read,
357       'W' for write, or 'D' for  block  discard  operation),  and  optionally
358       either  a  'B'  (for barrier operations) or 'S' (for synchronous opera‐
359       tions).
360
361
362

DEFAULT OUTPUT

364       The standard header (or initial fields displayed) include:
365
366           "%D %2c %8s %5T.%9t %5p %2a %3d"
367
368       Breaking this down:
369
370
371       %D     Displays the event's device major/minor as: %3d,%-3d.
372
373
374       %2c    CPU ID (2-character field).
375
376
377       %8s    Sequence number
378
379
380       %5T.%9t
381              5-character field for the seconds portion of the time stamp  and
382              a 9-character field for the nanoseconds in the time stamp.
383
384
385       %5p    5-character field for the process ID.
386
387
388       %2a    2-character field for one of the actions.
389
390
391       %3d    3-character field for the RWBS data.
392
393              Seeing this in action:
394
395                  8,0     3         1      0.000000000   697  G   W 223490 + 8
396              [kjournald]
397
398              The header is the data in this line up to the  223490  (starting
399              block).   The  default  output for all event types includes this
400              header.
401
402
403
404

DEFAULT OUTPUT PER ACTION

406       C -- complete
407           If a payload is present, this is presented between parenthesis fol‐
408           lowing the header, followed by the error value.
409
410           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 either case,
413           it is followed by the error value for the completion.
414
415       B -- bounced
416       D -- issued
417       I -- inserted
418       Q -- queued
419           If a payload is present, the number of  payload  bytes  is  output,
420           followed by the payload in hexadecimal between parenthesis.
421
422           If  no payload is present, the sector and number of blocks are pre‐
423           sented (with an intervening plus (+) character). If the  -t  option
424           was specified, then the elapsed time is presented (in parenthesis).
425           In either case, it is followed by the command associated  with  the
426           event (surrounded by square brackets).
427
428       F -- front merge
429       G -- get request
430       M -- back merge
431       S -- sleep
432           The  starting sector and number of blocks is output (with an inter‐
433           vening plus (+) character), followed by the command associated with
434           the event (surrounded by square brackets).
435
436       P -- plug
437           The  command associated with the event (surrounded by square brack‐
438           ets) is output.
439
440       U -- unplug
441       T -- unplug due to timer
442           The command associated with the event (surrounded by square  brack‐
443           ets) is output, followed by the number of requests outstanding.
444
445       X -- split
446           The  original starting sector followed by the new sector (separated
447           by a slash (/) is output, followed by the command  associated  with
448           the event (surrounded by square brackets).
449
450       A -- remap
451           Sector  and  length  is  output, along with the original device and
452           sector offset.
453
454
455

EXAMPLES

457       To trace the i/o on the device /dev/sda and parse the output  to  human
458       readable form, use the following command:
459
460           % blktrace -d /dev/sda -o - | blkparse -i -
461
462       (see  blktrace  (8)  for more information).  This same behaviour can be
463       achieve with the convenience script btrace.  The command
464
465           % btrace /dev/sda
466
467       has exactly the same effect as the previous command. See btrace (8) for
468       more information.
469
470       To  trace  the i/o on a device and save the output for later processing
471       with blkparse, use blktrace like this:
472
473           % blktrace /dev/sda /dev/sdb
474
475       This will trace i/o on the devices /dev/sda and /dev/sdb and  save  the
476       recorded information in the files sda and sdb in the current directory,
477       for the two different devices, respectively.   This  trace  information
478       can later be parsed by the blkparse utility:
479
480           % blkparse sda sdb
481
482       which  will output the previously recorded tracing information in human
483       readable form to stdout.
484
485
486

AUTHORS

488       blkparse was written by Jens Axboe, Alan D. Brunelle and Nathan  Scott.
489       This  man  page  was  created  from  the  blktrace documentation by Bas
490       Zoetekouw.
491
492
493

REPORTING BUGS

495       Report bugs to <linux-btrace@vger.kernel.org>
496
497
499       Copyright © 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
500       This is free software.  You may redistribute copies  of  it  under  the
501       terms       of       the      GNU      General      Public      License
502       <http://www.gnu.org/licenses/gpl.html>.  There is NO WARRANTY,  to  the
503       extent permitted by law.
504       This  manual  page  was  created  for  Debian by Bas Zoetekouw.  It was
505       derived from the documentation provided by the authors and  it  may  be
506       used,  distributed and modified under the terms of the GNU General Pub‐
507       lic License, version 2.
508       On Debian systems, the text of the GNU General Public  License  can  be
509       found in /usr/share/common-licenses/GPL-2.
510
511

SEE ALSO

513       btrace  (8),  blktrace  (8), verify_blkparse (1), blkrawverify (1), btt
514       (1)
515
516
517
518
519blktrace git-20070306202522     March  6, 2007                     BLKPARSE(1)
Impressum