doc/btt.1

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