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