Commit | Line | Data |
---|---|---|
fbdf23ec | 1 | .TH BLKPARSE 1 "March 6, 2007" "blktrace git\-20070306202522" "" |
98eee4e4 JA |
2 | |
3 | ||
4 | .SH NAME | |
5 | blkparse \- produce formatted output of event streams of block devices | |
6 | ||
7 | ||
8 | .SH SYNOPSIS | |
9 | .B blkparse [ \fIoptions\fR ] | |
10 | .br | |
11 | ||
12 | ||
13 | .SH DESCRIPTION | |
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 | |
18 | form. | |
19 | ||
20 | As with \fIblktrace\fR, some details concerning \fIblkparse\fR | |
21 | will help in understanding the command line options presented below. | |
22 | ||
23 | ||
24 | .TP 2 | |
25 | \- | |
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. | |
29 | ||
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. | |
32 | An example would be: | |
33 | ||
34 | % blktrace \-d /dev/sda \-o \- | blkparse \-i \- | |
35 | ||
36 | .TP 2 | |
37 | \- | |
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. | |
40 | ||
41 | .TP 2 | |
42 | \- | |
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 | |
45 | \fB\-i\fR option. | |
46 | ||
47 | .TP 2 | |
48 | \- | |
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. | |
51 | ||
52 | .PP | |
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 | |
56 | option. | |
57 | ||
58 | ||
59 | ||
60 | .SH OPTIONS | |
541c9bf6 ES |
61 | \-A \fIhex-mask\fR |
62 | .br | |
63 | \-\-set-mask=\fIhex-mask\fR | |
64 | .RS | |
65 | Set filter mask to \fIhex-mask\fR, see blktrace (8) for masks | |
66 | .RE | |
67 | ||
68 | \-a \fImask\fR | |
69 | .br | |
70 | \-\-act-mask=\fImask\fR | |
71 | .RS | |
72 | Add \fImask\fR to current filter, see blktrace (8) for masks | |
73 | .RE | |
74 | ||
75 | \-D \fIdir\fR | |
76 | .br | |
77 | \-\-input-directory=\fIdir\fR | |
78 | .RS | |
79 | Prepend \fIdir\fR to input file names | |
80 | .RE | |
98eee4e4 JA |
81 | |
82 | \-b \fIbatch\fR | |
83 | .br | |
84 | \-\-batch={batch} | |
85 | .RS | |
86 | Standard input read batching | |
87 | .RE | |
88 | ||
89 | \-i \fIfile\fR | |
90 | .br | |
91 | \-\-input=\fIfile\fR | |
92 | .RS | |
93 | Specifies base name for input files \-\- default is \fIdevice\fR.blktrace.\fIcpu\fR. | |
94 | ||
95 | As noted above, specifying \fB\-i \-\fR runs in live mode with blktrace | |
96 | (reading data from standard in). | |
97 | .RE | |
98 | ||
99 | \-F \fItyp,fmt\fR | |
100 | .br | |
101 | \-\-format=\fItyp,fmt\fR | |
102 | .br | |
103 | \-f \fIfmt\fR | |
104 | .br | |
105 | \-\-format\-spec=\fIfmt\fR | |
106 | .RS | |
107 | Sets output format | |
108 | (See OUTPUT DESCRIPTION AND FORMATTING for details.) | |
109 | ||
110 | The \-f form specifies a format for all events | |
111 | ||
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. | |
115 | .RE | |
116 | ||
19cfaf3f AB |
117 | \-M |
118 | .br | |
119 | \-\-no-msgs | |
120 | .RS | |
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.) | |
124 | .RE | |
125 | ||
98eee4e4 JA |
126 | \-h |
127 | .br | |
128 | \-\-hash\-by\-name | |
129 | .RS | |
130 | Hash processes by name, not by PID | |
131 | .RE | |
132 | ||
133 | \-o \fIfile\fR | |
134 | .br | |
135 | \-\-output=\fIfile\fR | |
136 | .RS | |
137 | Output file | |
138 | .RE | |
139 | ||
140 | \-O | |
141 | .br | |
142 | \-\-no\-text\-output | |
143 | .RS | |
144 | Do \fInot\fR produce text output, used for binary (\fB\-d\fR) only | |
145 | .RE | |
146 | ||
147 | \-d \fIfile\fR | |
148 | .br | |
149 | \-\-dump\-binary=\fIfile\fR | |
150 | .RS | |
151 | Binary output file | |
152 | .RE | |
153 | ||
154 | \-q | |
155 | .br | |
156 | \-\-quiet | |
157 | .RS | |
158 | Quiet mode | |
159 | .RE | |
160 | ||
161 | \-s | |
162 | .br | |
163 | \-\-per\-program\-stats | |
164 | .RS | |
165 | Displays data sorted by program | |
166 | .RE | |
167 | ||
a7263b8f WZ |
168 | \-S \fIevent\fR |
169 | .br | |
170 | \-\-sort\-program\-stats=\fIevent\fR | |
171 | .br | |
172 | .RS | |
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. | |
176 | ||
177 | If you want to soct programs by how many data they queued, you can use: | |
178 | ||
179 | blkparse -i sda.blktrace. -q \-S Q \-o sda.parse | |
180 | .RE | |
181 | ||
182 | ||
98eee4e4 JA |
183 | \-t |
184 | .br | |
185 | \-\-track\-ios | |
186 | .RS | |
187 | Display time deltas per IO | |
188 | .RE | |
189 | ||
190 | \-w \fIspan\fR | |
191 | .br | |
192 | \-\-stopwatch=\fIspan\fR | |
193 | .RS | |
194 | Display traces for the \fIspan\fR specified \-\- where span can be: | |
195 | .br | |
196 | \fIend\-time\fR \-\- Display traces from time 0 through \fIend\-time\fR (in ns) | |
197 | .br | |
198 | or | |
199 | .br | |
200 | \fIstart:end\-time\fR \-\- Display traces from time \fIstart\fR | |
201 | through end\-time (in ns). | |
202 | .RE | |
203 | ||
204 | \-v | |
205 | .br | |
206 | \-\-verbose | |
207 | .RS | |
208 | More verbose marginal on marginal errors | |
209 | .RE | |
210 | ||
211 | \-V | |
212 | .br | |
213 | \-\-version | |
214 | .RS | |
215 | Display version | |
216 | .RE | |
217 | ||
218 | ||
219 | .SH "TRACE ACTIONS" | |
220 | The following trace actions are recognised: | |
221 | ||
222 | .HP 4 | |
223 | \fBC -- complete\fR | |
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. | |
226 | ||
227 | .HP 4 | |
228 | \fBD -- issued\fR | |
229 | A request that previously resided on the block layer queue or in the i/o | |
230 | scheduler has been sent to the driver. | |
231 | ||
232 | .HP 4 | |
233 | \fBI -- inserted\fR | |
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. | |
236 | ||
237 | .HP 4 | |
238 | \fBQ -- queued\fR | |
239 | This notes intent to queue i/o at the given location. No real requests exists | |
240 | yet. | |
241 | ||
242 | .HP 4 | |
243 | \fBB -- bounced\fR | |
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. | |
249 | ||
250 | .HP 4 | |
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. | |
254 | ||
255 | .HP 4 | |
256 | \fBF -- front merge\fR | |
257 | Same as the back merge, except this i/o ends where a previously inserted | |
258 | requests starts. | |
259 | ||
98eee4e4 JA |
260 | .HP 4 |
261 | \fBM -- front or back merge\fR | |
262 | One of the above. | |
263 | ||
264 | .HP 4 | |
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. | |
268 | ||
269 | .HP 4 | |
270 | \fBS -- sleep\fR | |
271 | No available request structures were available, so the issuer has to wait for | |
272 | one to be freed. | |
273 | ||
274 | .HP 4 | |
275 | \fBP -- plug\fR | |
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. | |
278 | ||
279 | .HP 4 | |
280 | \fBU -- unplug\fR | |
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. | |
284 | ||
285 | .HP 4 | |
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. | |
289 | ||
290 | .HP 4 | |
291 | \fBX -- split\fR | |
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. | |
297 | ||
298 | .HP 4 | |
299 | \fBA -- remap\fR | |
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. | |
302 | ||
93d9e5b5 WZ |
303 | .HP 4 |
304 | \fBR -- requeue\fR | |
305 | Put a request back on queue. | |
306 | ||
98eee4e4 JA |
307 | |
308 | ||
309 | ||
310 | .SH "OUTPUT DESCRIPTION AND FORMATTING" | |
311 | ||
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: | |
315 | ||
316 | .IP \fBa\fR 4 | |
317 | Action, a (small) string (1 or 2 characters) -- see table below for more details | |
318 | ||
319 | .IP \fBc\fR 4 | |
320 | CPU id | |
321 | ||
322 | .IP \fBC\fR 4 | |
323 | Command | |
324 | ||
325 | .IP \fBd\fR 4 | |
326 | RWBS field, a (small) string (1-3 characters) -- see section below for more details | |
327 | ||
328 | .IP \fBD\fR 4 | |
329 | 7-character string containing the major and minor numbers of | |
330 | the event's device (separated by a comma). | |
331 | ||
332 | .IP \fBe\fR 4 | |
333 | Error value | |
334 | ||
7238673f JK |
335 | .IP \fBg\fR 4 |
336 | Cgroup identifier of the cgroup that generated the IO. Note that this requires | |
337 | appropriate kernel support (kernel version at least 4.14). | |
338 | ||
98eee4e4 JA |
339 | .IP \fBm\fR 4 |
340 | Minor number of event's device. | |
341 | ||
342 | .IP \fBM\fR 4 | |
343 | Major number of event's device. | |
344 | ||
345 | .IP \fBn\fR 4 | |
346 | Number of blocks | |
347 | ||
348 | .IP \fBN\fR 4 | |
349 | Number of bytes | |
350 | ||
351 | .IP \fBp\fR 4 | |
352 | Process ID | |
353 | ||
354 | .IP \fBP\fR 4 | |
355 | Display packet data \-\- series of hexadecimal values | |
356 | ||
357 | .IP \fBs\fR 4 | |
358 | Sequence numbers | |
359 | ||
360 | .IP \fBS\fR 4 | |
361 | Sector number | |
362 | ||
363 | .IP \fBt\fR 4 | |
364 | Time stamp (nanoseconds) | |
365 | ||
366 | .IP \fBT\fR 4 | |
367 | Time stamp (seconds) | |
368 | ||
369 | .IP \fBu\fR 4 | |
370 | Elapsed value in microseconds (\fI\-t\fR command line option) | |
371 | ||
372 | .IP \fBU\fR 4 | |
373 | Payload unsigned integer | |
374 | ||
09feee84 HM |
375 | .IP \fBz\fR 4 |
376 | The absolute time, as local time in your time zone, with no date displayed | |
377 | ||
98eee4e4 JA |
378 | .PP |
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. | |
383 | ||
384 | Thus, to specify the command in a 12-character field that is left aligned: | |
385 | ||
386 | \-f "%\-12C" | |
387 | ||
388 | ||
389 | .SH "ACTION IDENTIFIERS" | |
390 | ||
391 | The following table shows the various actions which may be output: | |
392 | ||
393 | .IP A | |
394 | IO was remapped to a different device | |
395 | ||
396 | .IP B | |
397 | IO bounced | |
398 | ||
399 | .IP C | |
400 | IO completion | |
401 | ||
402 | .IP D | |
403 | IO issued to driver | |
404 | ||
405 | .IP F | |
406 | IO front merged with request on queue | |
407 | ||
408 | .IP G | |
409 | Get request | |
410 | ||
411 | .IP I | |
412 | IO inserted onto request queue | |
413 | ||
414 | .IP M | |
415 | IO back merged with request on queue | |
416 | ||
417 | .IP P | |
418 | Plug request | |
419 | ||
420 | .IP Q | |
421 | IO handled by request queue code | |
422 | ||
423 | .IP S | |
424 | Sleep request | |
425 | ||
426 | .IP T | |
427 | Unplug due to timeout | |
428 | ||
429 | .IP U | |
430 | Unplug request | |
431 | ||
432 | .IP X | |
433 | Split | |
434 | ||
435 | ||
436 | .SH "RWBS DESCRIPTION" | |
437 | ||
64c03161 DW |
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). | |
98eee4e4 JA |
441 | |
442 | ||
443 | .SH "DEFAULT OUTPUT" | |
444 | ||
445 | The standard header (or initial fields displayed) include: | |
446 | ||
447 | "%D %2c %8s %5T.%9t %5p %2a %3d" | |
448 | ||
449 | Breaking this down: | |
450 | ||
451 | .IP \fB%D\fR | |
452 | Displays the event's device major/minor as: %3d,%\-3d. | |
453 | ||
454 | .IP \fB%2c\fR | |
455 | CPU ID (2-character field). | |
456 | ||
457 | .IP \fB%8s\fR | |
458 | Sequence number | |
459 | ||
460 | .IP \fB%5T.%9t\fR | |
461 | 5-character field for the seconds portion of the time stamp and a 9-character field for the nanoseconds in the time stamp. | |
462 | ||
463 | .IP \fB%5p\fR | |
464 | 5-character field for the process ID. | |
465 | ||
466 | .IP \fB%2a\fR | |
467 | 2-character field for one of the actions. | |
468 | ||
469 | .IP \fB%3d\fR | |
470 | 3-character field for the RWBS data. | |
471 | ||
472 | Seeing this in action: | |
473 | ||
474 | 8,0 3 1 0.000000000 697 G W 223490 + 8 [kjournald] | |
475 | ||
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. | |
478 | ||
479 | ||
480 | ||
481 | .SH "DEFAULT OUTPUT PER ACTION" | |
482 | ||
483 | \fBC \-\- complete\fR | |
484 | .RS 4 | |
485 | If a payload is present, this is presented between | |
486 | parenthesis following the header, followed by the error value. | |
487 | ||
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. | |
492 | .RE | |
493 | ||
494 | \fBB \-\- bounced\fR | |
495 | .br | |
496 | \fBD \-\- issued\fR | |
497 | .br | |
498 | \fBI \-\- inserted\fR | |
499 | .br | |
500 | \fBQ \-\- queued\fR | |
501 | .RS 4 | |
502 | If a payload is present, the number of payload bytes | |
503 | is output, followed by the payload in hexadecimal between parenthesis. | |
504 | ||
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). | |
510 | .RE | |
511 | ||
512 | \fBF \-\- front merge\fR | |
513 | .br | |
514 | \fBG \-\- get request\fR | |
515 | .br | |
516 | \fBM \-\- back merge\fR | |
517 | .br | |
518 | \fBS \-\- sleep\fR | |
519 | .RS 4 | |
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). | |
523 | .RE | |
524 | ||
525 | \fBP \-\- plug\fR | |
526 | .RS 4 | |
527 | The command associated with the event (surrounded by | |
528 | square brackets) is output. | |
529 | .RE | |
530 | ||
531 | \fBU \-\- unplug\fR | |
532 | .br | |
533 | \fBT \-\- unplug due to timer\fR | |
534 | .RS 4 | |
535 | The command associated with the event | |
536 | (surrounded by square brackets) is output, followed by the number of | |
537 | requests outstanding. | |
538 | .RE | |
539 | ||
540 | \fBX \-\- split\fR | |
541 | .RS 4 | |
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). | |
545 | .RE | |
546 | ||
547 | \fBA \-\- remap\fR | |
548 | .RS 4 | |
549 | Sector and length is output, along with the original | |
550 | device and sector offset. | |
551 | .RE | |
552 | ||
553 | ||
554 | .SH EXAMPLES | |
88d38b4d | 555 | To trace the i/o on the device \fI/dev/sda\fB and parse the output to human |
98eee4e4 JA |
556 | readable form, use the following command: |
557 | ||
558 | % blktrace \-d /dev/sda \-o \- | blkparse \-i \- | |
559 | ||
560 | (see \fIblktrace\fR (8) for more information). | |
561 | This same behaviour can be achieve with the convenience script \fIbtrace\fR. | |
562 | The command | |
563 | ||
564 | % btrace /dev/sda | |
565 | ||
566 | has exactly the same effect as the previous command. See \fIbtrace\fR (8) for | |
567 | more information. | |
568 | ||
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: | |
571 | ||
572 | % blktrace /dev/sda /dev/sdb | |
573 | ||
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: | |
578 | ||
579 | % blkparse sda sdb | |
580 | ||
581 | which will output the previously recorded tracing information in human | |
582 | readable form to stdout. | |
583 | ||
584 | ||
585 | .SH AUTHORS | |
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. | |
588 | ||
589 | ||
590 | .SH "REPORTING BUGS" | |
591 | Report bugs to <linux\-btrace@vger.kernel.org> | |
592 | ||
593 | .SH COPYRIGHT | |
594 | Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. | |
595 | .br | |
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. | |
599 | .br | |
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. | |
603 | .br | |
604 | On Debian systems, the text of the GNU General Public License can be found in | |
605 | /usr/share/common\-licenses/GPL\-2. | |
606 | ||
607 | .SH "SEE ALSO" | |
608 | btrace (8), blktrace (8), verify_blkparse (1), blkrawverify (1), btt (1) | |
609 |