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