Commit | Line | Data |
---|---|---|
9a8e0e17 | 1 | .TH BTT 1 "September 29, 2007" "blktrace git\-20070910192508" "" |
98eee4e4 JA |
2 | |
3 | ||
4 | .SH NAME | |
5 | btt \- analyse block i/o traces produces by blktrace | |
6 | ||
7 | ||
8 | .SH SYNOPSIS | |
9a8e0e17 | 9 | .B btt |
fbdf23ec | 10 | .br |
9a8e0e17 | 11 | [ \-a | \-\-seek\-absolute ] |
4ae2c3c6 | 12 | .br |
9a8e0e17 BZ |
13 | [ \-A | \-\-all\-data ] |
14 | .br | |
15 | [ \-B <\fIoutput name\fR> | \-\-dump\-blocknos=<\fIoutput name\fR> ] | |
16 | .br | |
17 | [ \-d <\fIseconds\fR> | \-\-range\-delta=<\fIseconds\fR> ] | |
18 | .br | |
19 | [ \-D <\fIdev;...\fR> | \-\-devices=<\fIdev;...\fR> ] | |
20 | .br | |
21 | [ \-e <\fIexe,...\fR> | \-\-exes=<\fIexe,...\fR> ] | |
22 | .br | |
23 | [ \-h | \-\-help ] | |
24 | .br | |
25 | [ \-i <\fIinput name\fR> | \-\-input\-file=<\fIinput name\fR> ] | |
26 | .br | |
27 | [ \-I <\fIoutput name\fR> | \-\-iostat=<\fIoutput name\fR> ] | |
28 | .br | |
29 | [ \-l <\fIoutput name\fR> | \-\-d2c\-latencies=<\fIoutput name\fR> ] | |
30 | .br | |
2baef508 AB |
31 | [ \-L <\fIfreq\fR> | \-\-periodic\-latencies=<\fIfreq\fR> ] |
32 | .br | |
5798ffb2 ES |
33 | [ \-m <\fIoutput name\fR> | \-\-seeks\-per\-second=<\fIoutput name\fR> ] |
34 | .br | |
9a8e0e17 BZ |
35 | [ \-M <\fIdev map\fR> | \-\-dev\-maps=<\fIdev map\fR> |
36 | .br | |
37 | [ \-o <\fIoutput name\fR> | \-\-output\-file=<\fIoutput name\fR> ] | |
38 | .br | |
39 | [ \-p <\fIoutput name\fR> | \-\-per\-io\-dump=<\fIoutput name\fR> ] | |
40 | .br | |
a22df989 AB |
41 | [ \-P <\fIoutput name\fR> | \-\-per\-io\-trees=<\fIoutput name\fR> ] |
42 | .br | |
9a8e0e17 BZ |
43 | [ \-q <\fIoutput name\fR> | \-\-q2c\-latencies=<\fIoutput name\fR> ] |
44 | .br | |
4ae2c3c6 AB |
45 | [ \-Q <\fIoutput name\fR> | \-\-active\-queue\-depth=<\fIoutput name\fR> ] |
46 | .br | |
ee27874b AB |
47 | [ \-r | \-\-no\-remaps ] |
48 | .br | |
9a8e0e17 BZ |
49 | [ \-s <\fIoutput name\fR> | \-\-seeks=<\fIoutput name\fR> ] |
50 | .br | |
51 | [ \-S <\fIinterval\fR> | \-\-iostat\-interval=<\fIinterval\fR> ] | |
52 | .br | |
53 | [ \-t <\fIsec\fR> | \-\-time\-start=<\fIsec\fR> ] | |
98eee4e4 | 54 | .br |
9a8e0e17 | 55 | [ \-T <\fIsec\fR> | \-\-time\-end=<\fIsec\fR> ] |
98eee4e4 | 56 | .br |
9a8e0e17 | 57 | [ \-u <\fIoutput name\fR> | \-\-unplug\-hist=<\fIoutput name\fR> ] |
98eee4e4 | 58 | .br |
9a8e0e17 BZ |
59 | [ \-v | \-\-verbose ] |
60 | .br | |
61 | [ \-V | \-\-version ] | |
e47ada10 | 62 | .br |
5798ffb2 ES |
63 | [ \-X | \-\-easy\-parse\-avgs ] |
64 | .br | |
e47ada10 | 65 | [ \-z <\fIoutput name\fR> | \-\-q2d\-latencies=<\fIoutput name\fR> ] |
2e37a10e AB |
66 | .br |
67 | [ \-Z | \-\-do\-active ] | |
98eee4e4 JA |
68 | |
69 | ||
70 | .SH DESCRIPTION | |
71 | ||
9a8e0e17 BZ |
72 | btt is a post\-processing tool for the block layer IO tracing tool called |
73 | blktrace(8). As noted in its documentation, blktrace | |
74 | is a block layer IO tracing mechanism which provides detailed | |
75 | information about request queue operations up to user space. | |
76 | ||
98eee4e4 JA |
77 | btt will take in binary dump data from blkparse, and analyse the events, |
78 | producing a series of output from the analysis. It will also build .dat | |
9a8e0e17 | 79 | files containing "range data" \-\- showing things like Q activity (periods |
98eee4e4 JA |
80 | of time while Q events are being produced), C activity (likewise for |
81 | command completions), and etc. | |
82 | ||
ee43a143 | 83 | Included with the distribution is a simple 3D plotting utility, |
fbdf23ec | 84 | \fIbno_plot\fR, which can plot the block numbers btt outputs if the \fI-B\fR |
ee43a143 BZ |
85 | option is specified. The display will display each IO generated, with the time |
86 | (seconds) along the X-axis, the block number (start) along the Y-axis and the | |
87 | number of blocks transferred in the IO represented along the Z-axis. | |
88 | ||
98eee4e4 JA |
89 | |
90 | .SH OPTIONS | |
91 | ||
9a8e0e17 | 92 | .B \-a |
98eee4e4 | 93 | .br |
9a8e0e17 | 94 | .B \-\-seek\-absolute |
98eee4e4 | 95 | .RS 4 |
9a8e0e17 BZ |
96 | When specified on the command line, this directs btt to calculate |
97 | seek distances based solely upon the ending block address of one IO, | |
98 | and the start of the next. By default \fBbtt\fR uses the concept | |
99 | of the closeness to either the beginning or end of the previous IO. See | |
100 | the Users Manual for more details about seek distances. | |
98eee4e4 JA |
101 | .RE |
102 | ||
9a8e0e17 | 103 | .B \-A |
98eee4e4 | 104 | .br |
9a8e0e17 | 105 | .B \-\-all\-data |
98eee4e4 | 106 | .RS 4 |
9a8e0e17 BZ |
107 | Normally \fBbtt\fR will not print out verbose information concerning |
108 | per-process and per-device data. If you desire that level of detail you can | |
109 | specify this option. | |
98eee4e4 JA |
110 | .RE |
111 | ||
9a8e0e17 | 112 | .B \-B <\fIoutput name\fR> |
98eee4e4 | 113 | .br |
9a8e0e17 | 114 | .B \-\-dump\-blocknos=<\fIoutput name\fR> |
98eee4e4 | 115 | .RS 4 |
9a8e0e17 BZ |
116 | This option will output absolute block numbers to three files prefixed |
117 | by the specified output name: | |
118 | .HP | |
119 | .I prefix_device_r.dat | |
120 | .br | |
121 | All read block numbers are output, first column is time (seconds), second is | |
122 | the block number, and the third column is the ending block number. | |
123 | .HP | |
124 | .I prefix_device_w.dat | |
125 | .br | |
126 | All write block numbers are output, first column is time (seconds), second is | |
127 | the block number, and the third column is the ending block number. | |
128 | .HP | |
129 | .I prefix_device_c.dat | |
130 | .br | |
131 | All block numbers (read and write) are output, first column is time (seconds), | |
132 | second is the block number, and the third column is the ending block number. | |
98eee4e4 JA |
133 | .RE |
134 | ||
135 | .B \-d <\fIseconds\fR> | |
136 | .br | |
137 | .B \-\-range\-delta=<\fIseconds\fR> | |
138 | .RS 4 | |
9a8e0e17 BZ |
139 | \fBbtt\fR outputs a file containing Q and C activity, the notion of active |
140 | traces simply means that there are Q or C traces occurring within a certain | |
141 | period of each other. The default values is 0.1 seconds; with this option | |
142 | allowing one to change that granularity. The smaller the value, the more data | |
143 | points provided. | |
98eee4e4 JA |
144 | .RE |
145 | ||
146 | .B \-D <\fIdev;...\fR> | |
147 | .br | |
148 | .B \-\-devices=<\fIdev;...\fR> | |
149 | .RS 4 | |
9a8e0e17 BZ |
150 | Normally, \fBbtt\fR will produce data for all devices detected in the |
151 | traces parsed. With this option, one can reduce the analysis to one or more | |
152 | devices provided in the string passed to this option. The device identifiers | |
153 | are the major and minor number of each device, and each device identifier is | |
154 | separated by a colon (:). A valid specifier for devices 8,0 and 8,8 would then | |
155 | be: \fI8,0:8,8\fR. | |
98eee4e4 JA |
156 | .RE |
157 | ||
158 | .B \-e <\fIexe,...\fR> | |
159 | .br | |
160 | .B \-\-exes=<\fIexe,...\fR> | |
161 | .RS 4 | |
162 | The \-e option supplies the list of executables that will have I/Os | |
163 | analysed. | |
164 | .RE | |
165 | ||
9a8e0e17 BZ |
166 | .B \-h |
167 | .br | |
168 | .B \-\-help | |
169 | .RS 4 | |
170 | Shows a short summary of possible command line option | |
171 | .RE | |
172 | ||
173 | .B \-i <\fIinput name\fR> | |
174 | .br | |
175 | .B \-\-input\-file <\fIinput file\fR> | |
176 | .RS 4 | |
177 | Specifies the input file to analyse. This should be a trace file produced | |
178 | by \fIblktrace\fR (8). | |
179 | .RE | |
180 | ||
98eee4e4 JA |
181 | .B \-I <\fIoutput name\fR> |
182 | .br | |
183 | .B \-\-iostat=<\fIoutput name\fR> | |
184 | .RS 4 | |
185 | The \-I option directs btt to output iostat\-like data to the specified | |
186 | file. Refer to the iostat (sysstat) documentation for details on the | |
187 | data columns. | |
188 | .RE | |
189 | ||
190 | .B \-l <\fIoutput name\fR> | |
191 | .br | |
192 | .B \-\-d2c\-latencies=<\fIoutput name\fR> | |
193 | .RS 4 | |
194 | The \-l option allows one to output per\-IO D2C latencies | |
195 | respectively. The supplied argument provides the basis for the output | |
196 | name for each device. | |
197 | .RE | |
198 | ||
2baef508 AB |
199 | .B \-L <\fIfreq\fR> |
200 | .br | |
201 | .B \-\-periodic\-latencies=<\fIfreq\fR> | |
202 | .RS 4 | |
203 | The \-L option allows one to output periodic latency information for both | |
204 | Q2C and D2C latencies. The frequency specified will regulate how often | |
205 | an average latency is output -- a floating point value expressing seconds. | |
206 | .RE | |
207 | ||
5798ffb2 ES |
208 | .B \-m <\fIoutput name\fR> |
209 | .br | |
210 | .B \-\-seeks\-per\-second=<\fIoutput name\fR> | |
211 | .RS 4 | |
212 | Trigger btt to output seeks-per-second information. The first column will | |
213 | contain a time value (seconds), and the second column will indicate the | |
214 | number of seeks per second at that point. | |
215 | .RE | |
216 | ||
98eee4e4 JA |
217 | .B \-M <\fIdev map\fR> |
218 | .br | |
219 | .B \-\-dev\-maps=<\fIdev map\fR> | |
220 | .RS 4 | |
221 | The \-M option takes in a file generated by the provided script | |
222 | (gen_disk_info.py), and allows for better output of device names. | |
223 | .RE | |
224 | ||
225 | .B \-o <\fIoutput name\fR> | |
226 | .br | |
227 | .B \-\-output\-file=<\fIoutput name\fR> | |
228 | .RS 4 | |
229 | Specifies the output file name. | |
230 | .RE | |
231 | ||
232 | .B \-p <\fIoutput name\fR> | |
233 | .br | |
234 | .B \-\-per\-io\-dump=<\fIoutput name\fR> | |
235 | .RS 4 | |
236 | The \-p option will generate a file that contains a list of all IO | |
237 | "sequences" \- showing the parts of each IO (Q, A, I/M, D, & C). | |
238 | .RE | |
239 | ||
a22df989 AB |
240 | .B \-P <\fIoutput name\fR> |
241 | .br | |
242 | .B \-\-per\-io\-trees=<\fIoutput name\fR> | |
243 | .RS 4 | |
244 | The \-P option will generate a file that contains a list of all IO | |
245 | "sequences" \- showing only the Q, D & C operation times. The D & C | |
246 | time values are separated from the Q time values with a vertical bar. | |
247 | .RE | |
248 | ||
98eee4e4 JA |
249 | .B \-q <\fIoutput name\fR> |
250 | .br | |
251 | .B \-\-q2c\-latencies=<\fIoutput name\fR> | |
252 | .RS 4 | |
253 | The \-q option allows one to output per\-IO Q2C latencies | |
254 | respectively. The supplied argument provides the basis for the output | |
255 | name for each device. | |
256 | .RE | |
257 | ||
4ae2c3c6 AB |
258 | .B \-Q <\fIoutput name\fR> |
259 | .br | |
260 | .B \-\-active\-queue\-depth=<\fIoutput name\fR> | |
261 | .RS 4 | |
262 | The \-Q option allows one to output data files showing the time stamp | |
263 | and the depth of active commands (those issued but not completed). | |
264 | .RE | |
265 | ||
ee27874b AB |
266 | .B \-r |
267 | .br | |
268 | .B \-\-no\-remaps | |
269 | .RS 4 | |
270 | Ignore remap traces; older kernels did not implement the full remap | |
271 | PDU. | |
272 | .RE | |
273 | ||
98eee4e4 JA |
274 | .B \-s <\fIoutput name\fR> |
275 | .br | |
276 | .B \-\-seeks=<\fIoutput name\fR> | |
277 | .RS 4 | |
278 | The \-s option instructs btt to output seek data, the argument provided | |
279 | is the basis for file names output. There are two files per device, | |
280 | read seeks and write seeks. | |
281 | .RE | |
282 | ||
283 | .B \-S <\fIinterval\fR> | |
284 | .br | |
285 | .B \-\-iostat\-interval=<\fIinterval\fR> | |
286 | .RS 4 | |
287 | The \-S option specifies the interval to use between data | |
288 | output, it defaults to once per second. | |
289 | .RE | |
290 | ||
291 | .B \-t <\fIsec\fR> | |
292 | .br | |
293 | .B \-\-time\-start=<\fIsec\fR> | |
294 | .br | |
295 | .B \-T <\fIsec\fR> | |
296 | .br | |
297 | .B \-\-time\-end=<\fIsec\fR> | |
298 | .RS 4 | |
299 | The \-t/\-T options allow one to set a start and/or end time for analysing | |
300 | \- analysing will only be done for traces after \-t's argument and before | |
301 | \-T's argument. (\-t and \-T are optional, so if you specify just \-t, | |
302 | analysis will occur for all traces after the time specified. Similarly, | |
303 | if only \-T is specified, analysis stops after \-T's seconds.) | |
304 | .RE | |
305 | ||
9a8e0e17 BZ |
306 | .B \-u <\fIoutput name\fR> |
307 | .br | |
308 | .B \-\-unplug\-hist=<\fIoutput name\fR> | |
309 | .RS 4 | |
310 | This option instructs \fBbtt\fR to generate a data file containing histogram | |
311 | information for unplug traces on a per device basis. It shows how many | |
312 | times an unplug was hit with a specified number of IOs released. There are 21 | |
313 | output values into the file, as follows: | |
314 | ||
315 | .RS 4 | |
316 | a value of 0 represents 0..4 counts | |
317 | .br | |
318 | a value of 1 represents 5..9 counts | |
319 | .br | |
320 | a value of 2 represents 10..14 counts | |
321 | .br | |
322 | etc, until | |
323 | .br | |
324 | a value of 20 represents 100+ counts | |
325 | .br | |
326 | .RE | |
327 | ||
328 | The file name(s) generated use the text string passed as an argument for | |
329 | the prefix, followed by the device identifier in \fImajor,minor\fR | |
330 | form, with a \fI.dat\fR extension. For example, with \fI\-u | |
331 | up_hist\fR specified on the command line: \fIup_hist_008,032.dat\fR. | |
332 | .RE | |
333 | ||
334 | .B \-V | |
335 | .br | |
336 | .B \-\-version | |
337 | .RS 4 | |
338 | Shows the version of btt. | |
339 | .RE | |
340 | ||
98eee4e4 JA |
341 | .B \-v |
342 | .br | |
343 | .B \-\-verbose | |
344 | .RS 4 | |
345 | Requests a more verbose output. | |
346 | .RE | |
347 | ||
5798ffb2 ES |
348 | .B \-X |
349 | .br | |
350 | .B \-\-easy\-parse\-avgs | |
351 | .RS 4 | |
352 | Provide data in an easy-to-parse form and write it to a file | |
353 | with .avg exentsion | |
354 | .RE | |
355 | ||
e47ada10 AB |
356 | .B \-z <\fIoutput name\fR> |
357 | .br | |
358 | .B \-\-q2d\-latencies=<\fIoutput name\fR> | |
359 | .RS 4 | |
360 | The \-z option allows one to output per\-IO Q2D latencies | |
361 | respectively. The supplied argument provides the basis for the output | |
362 | name for each device. | |
363 | .RE | |
364 | ||
2e37a10e AB |
365 | .B \-Z |
366 | .br | |
367 | .B \-\-do\-active | |
368 | .RS 4 | |
369 | The \-Z will output files containing data which can be plotted showing | |
370 | per\-device (and total system) I/O activity. | |
371 | .RE | |
372 | ||
98eee4e4 JA |
373 | |
374 | .SH AUTHORS | |
e47ada10 AB |
375 | \fIbtt\fR was written by Alan D. Brunelle. This man page was created |
376 | from the \fIblktrace\fR documentation by Bas Zoetekouw. | |
98eee4e4 JA |
377 | |
378 | ||
379 | .SH "REPORTING BUGS" | |
380 | Report bugs to <linux\-btrace@vger.kernel.org> | |
381 | ||
382 | .SH COPYRIGHT | |
383 | Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. | |
384 | .br | |
385 | This is free software. You may redistribute copies of it under the terms of | |
386 | the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. | |
387 | There is NO WARRANTY, to the extent permitted by law. | |
388 | .br | |
389 | This manual page was created for Debian by Bas Zoetekouw. It was derived from | |
390 | the documentation provided by the authors and it may be used, distributed and | |
391 | modified under the terms of the GNU General Public License, version 2. | |
392 | .br | |
393 | On Debian systems, the text of the GNU General Public License can be found in | |
394 | /usr/share/common\-licenses/GPL\-2. | |
395 | ||
396 | .SH "SEE ALSO" | |
9a8e0e17 BZ |
397 | The btt Users Guide, which can be found in /usr/share/doc/blktrace/btt.pdf |
398 | .br | |
ee43a143 | 399 | bno_plot (1), blktrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1) |
98eee4e4 | 400 |