Commit | Line | Data |
---|---|---|
d0ca268b JA |
1 | Block IO Tracing |
2 | ---------------- | |
3 | ||
e7c9f3ff NS |
4 | Written by Jens Axboe <axboe@suse.de> (initial version and kernel support), |
5 | Alan D. Brunelle (threading and splitup into two seperate programs), | |
6 | Nathan Scott <nathans@sgi.com> (bug fixes, process names, multiple devices) | |
05831aca JA |
7 | Also thanks to Tom Zanussi <zanussi@us.ibm.com> for good input and |
8 | patches. | |
d0ca268b JA |
9 | |
10 | ||
c1bd9d09 JA |
11 | Requirements |
12 | ------------ | |
13 | ||
c8255c5a JA |
14 | blktrace was integrated into the mainline kernel between 2.6.16 and 2.6.17-rc1. |
15 | The target trace needs to run on a kernel at least that new. The blktrace | |
16 | repository contains a kernel patch against 2.6.16 and will continue to do | |
17 | so until 2.6.17 is released. If you forgot where you got it, the url is: | |
c1bd9d09 JA |
18 | |
19 | rsync://rsync.kernel.org/pub/scm/linux/kernel/git/axboe/blktrace.git | |
20 | ||
6432fd98 JA |
21 | If you don't have git, you can get hourly snapshots from: |
22 | ||
23 | http://www.kernel.org/pub/linux/kernel/people/axboe/blktrace/ | |
24 | ||
b2a8adbf JA |
25 | The snapshots include the full git object database as well. kernel.org has |
26 | excessively long mirror times, so if you have git installed, you can pull | |
27 | the master tree from: | |
28 | ||
29 | git://brick.kernel.dk/data/git/blktrace.git | |
6432fd98 | 30 | |
ab9b41a7 JA |
31 | For browsing the repo over http and viewing history etc, you can direct |
32 | your browser to: | |
33 | ||
34 | http://brick.kernel.dk/git | |
35 | ||
c1bd9d09 JA |
36 | |
37 | Usage | |
38 | ----- | |
39 | ||
e94cf8d7 | 40 | $ blktrace -d <dev> [ -r debug_path ] [ -o output ] [ -k ] [ -w time ] |
ab197ca7 AB |
41 | [ -a action ] [ -A action mask ] |
42 | ||
43 | -d Use specified device. May also be given last after options. | |
e94cf8d7 | 44 | -r Path to mounted debugfs, defaults to /debug. |
ab197ca7 | 45 | -o File(s) to send output to. |
d1d7f15f | 46 | -D Directory to prepend to output file names. |
ab197ca7 AB |
47 | -k Kill running trace. |
48 | -w Stop after defined time, in seconds. | |
49 | -a Only trace specific actions (use more -a options to add actions). | |
50 | Available actions are: | |
51 | ||
d0009925 JA |
52 | READ |
53 | WRITE | |
54 | BARRIER | |
55 | SYNC | |
56 | QUEUE | |
57 | REQUEUE | |
58 | ISSUE | |
59 | COMPLETE | |
60 | FS | |
61 | PC | |
ab197ca7 AB |
62 | |
63 | -A Give the trace mask directly as a number. | |
64 | ||
129aa440 JA |
65 | -b Sub buffer size in KiB. |
66 | -n Number of sub buffers. | |
f531b94d JA |
67 | -l Run in network listen mode (blktrace server) |
68 | -h Run in network client mode, connecting to the given host | |
69 | -p Network port to use (default 8462) | |
79971f43 | 70 | -s Disable network client use of sendfile() to transfer data |
57ea8602 | 71 | -V Print program version info. |
52724a0e | 72 | |
ab197ca7 AB |
73 | $ blkparse -i <input> [ -o <output> ] [ -b rb_batch ] [ -s ] [ -t ] [ -q ] |
74 | [ -w start:stop ] [ -f output format ] [ -F format spec ] | |
a2594911 | 75 | [ -d <binary> ] |
ab197ca7 AB |
76 | |
77 | -i Input file containing trace data, or '-' for stdin. | |
d1d7f15f | 78 | -D Directory to prepend to input file names. |
ab197ca7 AB |
79 | -o Output file. If not given, output is stdout. |
80 | -b stdin read batching. | |
81 | -s Show per-program io statistics. | |
d915dee6 | 82 | -h Hash processes by name, not pid. |
ab197ca7 AB |
83 | -t Track individual ios. Will tell you the time a request took to |
84 | get queued, to get dispatched, and to get completed. | |
85 | -q Quiet. Don't display any stats at the end of the trace. | |
86 | -w Only parse data between the given time interval in seconds. If | |
87 | 'start' isn't given, blkparse defaults the start time to 0. | |
a2594911 | 88 | -d Dump sorted data in binary format |
ab197ca7 AB |
89 | -f Output format. Customize the output format. The format field |
90 | identifiers are: | |
91 | ||
92 | %a - Action | |
93 | %c - CPU ID | |
94 | %C - Task command name | |
95 | %d - Direction (r/w) | |
96 | %D - Device number | |
97 | %e - Error number | |
98 | %M - Major | |
99 | %m - Minor | |
1c8ca7b5 JA |
100 | %N - Number of bytes |
101 | %n - Number of sectors | |
ab197ca7 AB |
102 | %p - PID |
103 | %P - PDU | |
104 | %s - Sequence number | |
105 | %S - Sector number | |
106 | %t - Time (wallclock - nanoseconds) | |
107 | %T - Time (wallclock - seconds) | |
108 | %u - Time (processing - microseconds) | |
638c1923 | 109 | %U - Unplug depth |
ab197ca7 AB |
110 | |
111 | -F Format specification. The individual specifiers are: | |
112 | ||
a8f30e64 | 113 | A - Remap |
ab197ca7 AB |
114 | B - Back merge |
115 | C - Complete | |
116 | D - Issue | |
117 | F - Front merge | |
118 | G - Get request | |
b6076a9b | 119 | I - Insert |
ab197ca7 AB |
120 | M - Both front and back merge |
121 | P - Plug | |
122 | Q - Queue | |
123 | R - Requeue | |
124 | S - Sleep requests | |
125 | T - Unplug timer | |
126 | U - Unplug IO | |
93f1c611 JA |
127 | W - Bounce |
128 | X - Split | |
c1bd9d09 | 129 | |
57ea8602 JA |
130 | -v More verbose for marginal errors. |
131 | -V Print program version info. | |
c1bd9d09 | 132 | |
54aa4b1c JA |
133 | $ verify_blkparse filename |
134 | ||
135 | Verifies an output file from blkparse. All it does is check if | |
136 | the events in the file are correctly time ordered. If an entry | |
137 | is found that isn't ordered, it's dumped to stdout. | |
138 | ||
f17c879d AB |
139 | $ blkrawverify <dev> [<dev>...] |
140 | ||
141 | The blkrawverify utility can be used to verify data retrieved | |
142 | via blktrace. It will check for valid event formats, forward | |
143 | progressing sequence numbers and time stamps, also does reasonable | |
144 | checks for other potential issues within invidividual events. | |
145 | ||
146 | Errors found will be tracked in <dev>.verify.out. | |
54aa4b1c | 147 | |
d0009925 JA |
148 | If you want to do live tracing, you can pipe the data between blktrace |
149 | and blkparse: | |
150 | ||
151 | % blktrace -d <device> -o - | blkparse -i - | |
152 | ||
153 | This has a small risk of displaying some traces a little out of sync, since | |
154 | it will do batch sorts of input events. Similarly, you can do traces over | |
f531b94d | 155 | the network. The network 'server' must run: |
d0009925 | 156 | |
f531b94d JA |
157 | % blktrace -l |
158 | ||
159 | to listen to incoming blktrace connections, while the client should use | |
160 | ||
161 | % blktrace -d /dev/sda -h <server hostname> | |
162 | ||
163 | to connect and transfer data over the network. | |
d0009925 | 164 | |
d0009925 | 165 | |
b47d077d JA |
166 | Documentation |
167 | ------------- | |
168 | ||
169 | A users guide is distributed with the source. It is in latex, a | |
d372b4d9 JA |
170 | 'make docs' will build a PDF in doc/. You need tetex and latex installed |
171 | to build the document. | |
b47d077d JA |
172 | |
173 | ||
8d99d141 JA |
174 | Resources |
175 | --------- | |
176 | ||
177 | vger hosts a mailing list dedicated to btrace discussion and development. | |
178 | The list is called linux-btrace@vger.kernel.org, subscribe by sending | |
179 | a mail to majordomo@vger.kernel.org with 'subscribe linux-btrace' in | |
180 | the mail body. | |
181 | ||
182 | ||
183 | ||
c8255c5a | 184 | 2006-03-24, Jens Axboe <axboe@suse.de> |
c1bd9d09 | 185 |