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