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 .br
  11 [ \-a               | \-\-seek\-absolute ]
  12 .br
  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
  31 [ \-L <\fIfreq\fR>        | \-\-periodic\-latencies=<\fIfreq\fR> ]
  32 .br
  33 [ \-m <\fIoutput name\fR> | \-\-seeks\-per\-second=<\fIoutput name\fR> ]
  34 .br
  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
  41 [ \-P <\fIoutput name\fR> | \-\-per\-io\-trees=<\fIoutput name\fR> ]
  42 .br
  43 [ \-q <\fIoutput name\fR> | \-\-q2c\-latencies=<\fIoutput name\fR> ]
  44 .br
  45 [ \-Q <\fIoutput name\fR> | \-\-active\-queue\-depth=<\fIoutput name\fR> ]
  46 .br
  47 [ \-r               | \-\-no\-remaps ]
  48 .br
  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> ]
  54 .br
  55 [ \-T <\fIsec\fR>         | \-\-time\-end=<\fIsec\fR> ]
  56 .br
  57 [ \-u <\fIoutput name\fR> | \-\-unplug\-hist=<\fIoutput name\fR> ]
  58 .br
  59 [ \-v               | \-\-verbose ]
  60 .br
  61 [ \-V               | \-\-version ]
  62 .br
  63 [ \-X               | \-\-easy\-parse\-avgs ]
  64 .br
  65 [ \-z <\fIoutput name\fR> | \-\-q2d\-latencies=<\fIoutput name\fR> ]
  66 .br
  67 [ \-Z               | \-\-do\-active ]
  68
  69
  70 .SH DESCRIPTION
  71
  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
  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
  79 files containing "range data" \-\- showing things like Q activity (periods
  80 of time while Q events are being produced), C activity (likewise for
  81 command completions), and etc.
  82
  83 Included with the distribution is a simple 3D plotting utility,
  84 \fIbno_plot\fR, which can plot the block numbers btt outputs if the \fI-B\fR
  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
  89
  90 .SH OPTIONS
  91
  92 .B \-a
  93 .br
  94 .B \-\-seek\-absolute
  95 .RS 4
  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.
 101 .RE
 102
 103 .B \-A
 104 .br
 105 .B \-\-all\-data
 106 .RS 4
 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.
 110 .RE
 111
 112 .B \-B <\fIoutput name\fR>
 113 .br
 114 .B \-\-dump\-blocknos=<\fIoutput name\fR>
 115 .RS 4
 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.
 133 .RE
 134
 135 .B \-d <\fIseconds\fR>
 136 .br
 137 .B \-\-range\-delta=<\fIseconds\fR>
 138 .RS 4
 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.
 144 .RE
 145
 146 .B \-D <\fIdev;...\fR>
 147 .br
 148 .B \-\-devices=<\fIdev;...\fR>
 149 .RS 4
 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.
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 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
 341 .B \-v
 342 .br
 343 .B \-\-verbose
 344 .RS 4
 345 Requests a more verbose output.
 346 .RE
 347
 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
 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
 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
 373
 374 .SH AUTHORS
 375 \fIbtt\fR was written by Alan D. Brunelle.  This man page was created
 376 from the \fIblktrace\fR documentation by Bas Zoetekouw.
 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"
 397 The btt Users Guide, which can be found in /usr/share/doc/blktrace/btt.pdf
 398 .br
 399 bno_plot (1), blktrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)
 400