summaryrefslogtreecommitdiff
path: root/doc/blkparse.1
blob: cb21fea52cf892e99d49fd01210db7a3807e00bd (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
.TH BLKPARSE 1 "March  6, 2007" "blktrace git\-20070306202522" ""


.SH NAME
blkparse \- produce formatted output of event streams of block devices


.SH SYNOPSIS
.B blkparse [ \fIoptions\fR ] 
.br


.SH DESCRIPTION
The \fIblkparse\fR 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
\fIblktrace\fR utility and convert it to a nicely formatted and human-readable
form.

As with \fIblktrace\fR, some details concerning \fIblkparse\fR
will help in understanding the command line options presented below.


.TP 2
\-
By default, \fIblkparse\fR expects to run in a post-processing mode; one where
the trace events have been saved by a previous run of blktrace, and blkparse
is combining event streams and dumping formatted data.

blkparse may be run in a live manner concurrently with blktrace by specifying
\fB\-i \-\fR to blkparse, and combining it with the live option for blktrace.
An example would be:

   % blktrace \-d /dev/sda \-o \- | blkparse \-i \-

.TP 2
\-
You can set how many blkparse batches event reads via the \fB\-b\fR option, the
default is to handle events in batches of 512.

.TP 2
\-
If you have saved event traces in blktrace with different output names (via
the \fB\-o\fR option to blktrace), you must specify the same input name via the
\fB\-i\fR option.

.TP 2
\-
The format of the output data can be controlled via the \fB\-f\fR or \fB\-F\fR
options \-\- see OUTPUT DESCRIPTION AND FORMATTING for details.

.PP
By default, blkparse sends formatted data to standard output. This may
be changed via the \fB\-o\fR option, or text output can be disabled via the
\fB\-O\fR option. A merged binary stream can be produced using the \fB\-d\fR
option.



.SH OPTIONS
\-A \fIhex-mask\fR
.br
\-\-set-mask=\fIhex-mask\fR
.RS
Set filter mask to \fIhex-mask\fR, see blktrace (8) for masks
.RE

\-a \fImask\fR
.br
\-\-act-mask=\fImask\fR
.RS
Add \fImask\fR to current filter, see blktrace (8) for masks
.RE

\-D \fIdir\fR
.br
\-\-input-directory=\fIdir\fR
.RS
Prepend \fIdir\fR to input file names
.RE

\-b \fIbatch\fR
.br
\-\-batch={batch}
.RS
Standard input read batching
.RE

\-i \fIfile\fR
.br
\-\-input=\fIfile\fR
.RS
Specifies base name for input files \-\- default is \fIdevice\fR.blktrace.\fIcpu\fR.

As noted above, specifying \fB\-i \-\fR runs in live mode with blktrace
(reading data from standard in).
.RE

\-F \fItyp,fmt\fR
.br
\-\-format=\fItyp,fmt\fR
.br
\-f \fIfmt\fR
.br
\-\-format\-spec=\fIfmt\fR
.RS
Sets output format
(See OUTPUT DESCRIPTION AND FORMATTING for details.)

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 \fItyp\fR field is one of the
action specifiers described in ACTION IDENTIFIERS.
.RE

\-M
.br
\-\-no-msgs
.RS
When \-d is specified, this will stop messages from being output to the
file. (Can seriously reduce the size of the resultant file when using
the CFQ I/O scheduler.)
.RE

\-h
.br
\-\-hash\-by\-name
.RS
Hash processes by name, not by PID
.RE

\-o \fIfile\fR
.br
\-\-output=\fIfile\fR
.RS
Output file
.RE

\-O
.br
\-\-no\-text\-output
.RS
Do \fInot\fR produce text output, used for binary (\fB\-d\fR) only
.RE

\-d \fIfile\fR
.br
\-\-dump\-binary=\fIfile\fR
.RS
Binary output file
.RE

\-q
.br
\-\-quiet
.RS
Quiet mode
.RE

\-s
.br
\-\-per\-program\-stats
.RS
Displays data sorted by program
.RE

\-t
.br
\-\-track\-ios
.RS
Display time deltas per IO
.RE

\-w \fIspan\fR
.br
\-\-stopwatch=\fIspan\fR
.RS
Display traces for the \fIspan\fR specified \-\- where span can be:
.br
\fIend\-time\fR \-\- Display traces from time 0 through \fIend\-time\fR (in ns)
.br
or
.br
\fIstart:end\-time\fR \-\- Display traces from time \fIstart\fR
through end\-time (in ns).
.RE

\-v
.br
\-\-verbose
.RS
More verbose marginal on marginal errors
.RE

\-V
.br
\-\-version
.RS
Display version
.RE


.SH "TRACE ACTIONS"
The following trace actions are recognised:

.HP 4
\fBC -- complete\fR
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.

.HP 4
\fBD -- issued\fR
A request that previously resided on the block layer queue or in the i/o
scheduler has been sent to the driver.

.HP 4
\fBI -- inserted\fR
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.

.HP 4
\fBQ -- queued\fR
This notes intent to queue i/o at the given location.  No real requests exists
yet.

.HP 4
\fBB -- bounced\fR
The data pages attached to this \fIbio\fR 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.

.HP 4
\fBM -- back merge\fR
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.

.HP 4
\fBF -- front merge\fR
Same as the back merge, except this i/o ends where a previously inserted
requests starts.

.HP 4
\fBM -- front or back merge\fR
One of the above.

.HP 4
\fBG -- get request\fR
To send any type of request to a block device, a \fIstruct request\fR
container must be allocated first.

.HP 4
\fBS -- sleep\fR
No available request structures were available, so the issuer has to wait for
one to be freed.

.HP 4
\fBP -- plug\fR
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.

.HP 4
\fBU -- unplug\fR
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.

.HP 4
\fBT -- unplug due to timer\fR
If nobody requests the i/o that was queued after plugging the queue, Linux will
automatically unplug it after a defined period has passed.

.HP 4
\fBX -- split\fR
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.

.HP 4
\fBA -- remap\fR
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.

.HP 4
\fBR -- requeue\fR
Put a request back on queue.




.SH "OUTPUT DESCRIPTION AND FORMATTING"

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:

.IP \fBa\fR 4
Action, a (small) string (1 or 2 characters) -- see table below for more details

.IP \fBc\fR 4
CPU id

.IP \fBC\fR 4
Command

.IP \fBd\fR 4
RWBS field, a (small) string (1-3 characters)  -- see section below for more details

.IP \fBD\fR 4
7-character string containing the major and minor numbers of
the event's device (separated by a comma).

.IP \fBe\fR 4
Error value

.IP \fBm\fR 4
Minor number of event's device.

.IP \fBM\fR 4
Major number of event's device.

.IP \fBn\fR 4
Number of blocks

.IP \fBN\fR 4
Number of bytes

.IP \fBp\fR 4
Process ID

.IP \fBP\fR 4
Display packet data \-\- series of hexadecimal values

.IP \fBs\fR 4
Sequence numbers

.IP \fBS\fR 4
Sector number

.IP \fBt\fR 4
Time stamp (nanoseconds)

.IP \fBT\fR 4
Time stamp (seconds)

.IP \fBu\fR 4
Elapsed value in microseconds (\fI\-t\fR command line option)

.IP \fBU\fR 4
Payload unsigned integer

.PP
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"


.SH "ACTION IDENTIFIERS"

The following table shows the various actions which may be output:

.IP A
IO was remapped to a different device

.IP B
IO bounced

.IP C
IO completion

.IP D
IO issued to driver

.IP F
IO front merged with request on queue

.IP G
Get request

.IP I
IO inserted onto request queue

.IP M
IO back merged with request on queue

.IP P
Plug request

.IP Q
IO handled by request queue code

.IP S
Sleep request

.IP T
Unplug due to timeout

.IP U
Unplug request

.IP X
Split


.SH "RWBS DESCRIPTION"

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).


.SH "DEFAULT OUTPUT"

The standard header (or initial fields displayed) include:

    "%D %2c %8s %5T.%9t %5p %2a %3d"

Breaking this down:

.IP \fB%D\fR
Displays the event's device major/minor as: %3d,%\-3d.

.IP \fB%2c\fR
CPU ID (2-character field).

.IP \fB%8s\fR
Sequence number

.IP \fB%5T.%9t\fR
5-character field for the seconds portion of the time stamp and a 9-character field for the nanoseconds in the time stamp.

.IP \fB%5p\fR
5-character field for the process ID.

.IP \fB%2a\fR
2-character field for one of the actions.

.IP \fB%3d\fR
3-character field for the RWBS data.

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.



.SH "DEFAULT OUTPUT PER ACTION"

\fBC \-\- complete\fR
.RS 4
If a payload is present, this is presented between
parenthesis following the header, followed by the error value.

If no payload is present, the sector and number of blocks are presented
(with an intervening plus (+) character). If the \fB\-t\fR option
was specified, then the elapsed time is presented. In either case,
it is followed by the error value for the completion.
.RE

\fBB \-\- bounced\fR
.br
\fBD \-\- issued\fR
.br
\fBI \-\- inserted\fR
.br
\fBQ \-\- queued\fR
.RS 4
If a payload is present, the number of payload bytes
is output, followed by the payload in hexadecimal between parenthesis.

If no payload is present, the sector and number of blocks are presented
(with an intervening plus (+) character). If the \fB\-t\fR 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).
.RE

\fBF \-\- front merge\fR
.br
\fBG \-\- get request\fR
.br
\fBM \-\- back merge\fR
.br
\fBS \-\- sleep\fR
.RS 4
The starting sector and number of blocks is output
(with an intervening plus (+) character), followed by the command
associated with the event (surrounded by square brackets).
.RE

\fBP \-\- plug\fR
.RS 4
The command associated with the event (surrounded by
square brackets) is output.
.RE

\fBU \-\- unplug\fR
.br
\fBT \-\- unplug due to timer\fR
.RS 4
The command associated with the event
(surrounded by square brackets) is output, followed by the number of
requests outstanding.
.RE

\fBX \-\- split\fR
.RS 4
The original starting sector followed by the new
sector (separated by a slash (/) is output, followed by the command
associated with the event (surrounded by square brackets).
.RE

\fBA \-\- remap\fR
.RS 4
Sector and length is output, along with the original
device and sector offset.
.RE


.SH EXAMPLES
To trace the i/o on the device \fI/dev/sda\fB and parse the output to human
readable form, use the following command:

    % blktrace \-d /dev/sda \-o \- | blkparse \-i \-

(see \fIblktrace\fR (8) for more information).
This same behaviour can be achieve with the convenience script \fIbtrace\fR.
The command

    % btrace /dev/sda

has exactly the same effect as the previous command. See \fIbtrace\fR (8) for
more information.

To trace the i/o on a device and save the output for later processing with
\fIblkparse\fR, use \fIblktrace\fR like this:

    % blktrace /dev/sda /dev/sdb

This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save
the recorded information in the files \fIsda\fR and \fIsdb\fR in the current
directory, for the two different devices, respectively.  This trace
information can later be parsed by the \fIblkparse\fR utility:

    % blkparse sda sdb

which will output the previously recorded tracing information in human
readable form to stdout. 


.SH AUTHORS
\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.  This
man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw.


.SH "REPORTING BUGS"
Report bugs to <linux\-btrace@vger.kernel.org>

.SH COPYRIGHT
Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
.br
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.
.br
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.
.br
On Debian systems, the text of the GNU General Public License can be found in
/usr/share/common\-licenses/GPL\-2.

.SH "SEE ALSO"
btrace (8), blktrace (8), verify_blkparse (1), blkrawverify (1), btt (1)