-.TH BTT 1 "March 06, 2007" "blktrace git\-20070306202522" ""
+.TH BTT 1 "September 29, 2007" "blktrace git\-20070910192508" ""
.SH NAME
.SH SYNOPSIS
-.B btt [options] \-i <\fIinput file\fR>
+.B btt
.br
-.B btt \-h | \-\-help
+[ \-a | \-\-seek\-absolute ]
.br
-.B btt \-V | \-\-version
+[ \-A | \-\-all\-data ]
.br
+[ \-B <\fIoutput name\fR> | \-\-dump\-blocknos=<\fIoutput name\fR> ]
+.br
+[ \-d <\fIseconds\fR> | \-\-range\-delta=<\fIseconds\fR> ]
+.br
+[ \-D <\fIdev;...\fR> | \-\-devices=<\fIdev;...\fR> ]
+.br
+[ \-e <\fIexe,...\fR> | \-\-exes=<\fIexe,...\fR> ]
+.br
+[ \-h | \-\-help ]
+.br
+[ \-i <\fIinput name\fR> | \-\-input\-file=<\fIinput name\fR> ]
+.br
+[ \-I <\fIoutput name\fR> | \-\-iostat=<\fIoutput name\fR> ]
+.br
+[ \-l <\fIoutput name\fR> | \-\-d2c\-latencies=<\fIoutput name\fR> ]
+.br
+[ \-L <\fIfreq\fR> | \-\-periodic\-latencies=<\fIfreq\fR> ]
+.br
+[ \-m <\fIoutput name\fR> | \-\-seeks\-per\-second=<\fIoutput name\fR> ]
+.br
+[ \-M <\fIdev map\fR> | \-\-dev\-maps=<\fIdev map\fR>
+.br
+[ \-o <\fIoutput name\fR> | \-\-output\-file=<\fIoutput name\fR> ]
+.br
+[ \-p <\fIoutput name\fR> | \-\-per\-io\-dump=<\fIoutput name\fR> ]
+.br
+[ \-P <\fIoutput name\fR> | \-\-per\-io\-trees=<\fIoutput name\fR> ]
+.br
+[ \-q <\fIoutput name\fR> | \-\-q2c\-latencies=<\fIoutput name\fR> ]
+.br
+[ \-Q <\fIoutput name\fR> | \-\-active\-queue\-depth=<\fIoutput name\fR> ]
+.br
+[ \-r | \-\-no\-remaps ]
+.br
+[ \-s <\fIoutput name\fR> | \-\-seeks=<\fIoutput name\fR> ]
+.br
+[ \-S <\fIinterval\fR> | \-\-iostat\-interval=<\fIinterval\fR> ]
+.br
+[ \-t <\fIsec\fR> | \-\-time\-start=<\fIsec\fR> ]
+.br
+[ \-T <\fIsec\fR> | \-\-time\-end=<\fIsec\fR> ]
+.br
+[ \-u <\fIoutput name\fR> | \-\-unplug\-hist=<\fIoutput name\fR> ]
+.br
+[ \-v | \-\-verbose ]
+.br
+[ \-V | \-\-version ]
+.br
+[ \-X | \-\-easy\-parse\-avgs ]
+.br
+[ \-z <\fIoutput name\fR> | \-\-q2d\-latencies=<\fIoutput name\fR> ]
+.br
+[ \-Z | \-\-do\-active ]
.SH DESCRIPTION
+btt is a post\-processing tool for the block layer IO tracing tool called
+blktrace(8). As noted in its documentation, blktrace
+is a block layer IO tracing mechanism which provides detailed
+information about request queue operations up to user space.
+
btt will take in binary dump data from blkparse, and analyse the events,
producing a series of output from the analysis. It will also build .dat
-files containing "range data" -- showing things like Q activity (periods
+files containing "range data" \-\- showing things like Q activity (periods
of time while Q events are being produced), C activity (likewise for
command completions), and etc.
+Included with the distribution is a simple 3D plotting utility,
+\fIbno_plot\fR, which can plot the block numbers btt outputs if the \fI-B\fR
+option is specified. The display will display each IO generated, with the time
+(seconds) along the X-axis, the block number (start) along the Y-axis and the
+number of blocks transferred in the IO represented along the Z-axis.
+
.SH OPTIONS
-.B \-h
+.B \-a
.br
-.B \-\-help
+.B \-\-seek\-absolute
.RS 4
-Shows a short summary of possible command line option
+When specified on the command line, this directs btt to calculate
+seek distances based solely upon the ending block address of one IO,
+and the start of the next. By default \fBbtt\fR uses the concept
+of the closeness to either the beginning or end of the previous IO. See
+the Users Manual for more details about seek distances.
.RE
-.B \-V
+.B \-A
.br
-.B \-\-version
+.B \-\-all\-data
.RS 4
-Shows the version of btt.
+Normally \fBbtt\fR will not print out verbose information concerning
+per-process and per-device data. If you desire that level of detail you can
+specify this option.
.RE
-.B \-i
+.B \-B <\fIoutput name\fR>
.br
+.B \-\-dump\-blocknos=<\fIoutput name\fR>
.RS 4
-Specifies the input file to analyse. This should be a trace file as produces
-by \fIblktrace\fR (8).
+This option will output absolute block numbers to three files prefixed
+by the specified output name:
+.HP
+.I prefix_device_r.dat
+.br
+All read block numbers are output, first column is time (seconds), second is
+the block number, and the third column is the ending block number.
+.HP
+.I prefix_device_w.dat
+.br
+All write block numbers are output, first column is time (seconds), second is
+the block number, and the third column is the ending block number.
+.HP
+.I prefix_device_c.dat
+.br
+All block numbers (read and write) are output, first column is time (seconds),
+second is the block number, and the third column is the ending block number.
.RE
.B \-d <\fIseconds\fR>
.br
.B \-\-range\-delta=<\fIseconds\fR>
.RS 4
-The \-d option allows you to specify the granularity which determines
-"activity" with regard to the .dat files \-\- this specific the time
-(in seconds) that must elapse without a particular event occurring to
-signify inactivity. The larger the number, the fewer ranges output \-\-
-the default is 0.1 seconds.
+\fBbtt\fR outputs a file containing Q and C activity, the notion of active
+traces simply means that there are Q or C traces occurring within a certain
+period of each other. The default values is 0.1 seconds; with this option
+allowing one to change that granularity. The smaller the value, the more data
+points provided.
.RE
.B \-D <\fIdev;...\fR>
.br
.B \-\-devices=<\fIdev;...\fR>
.RS 4
-The \-D option supplies the devices which should be looked at when
-analysing the input. This is a ":" separated list of devices, devices are
-specified by a mjr,mnr tuple (e.g.: \-D "8,0:8,8" specifies two devices
-with major 8 and minor 0 and 8 respectively).
+Normally, \fBbtt\fR will produce data for all devices detected in the
+traces parsed. With this option, one can reduce the analysis to one or more
+devices provided in the string passed to this option. The device identifiers
+are the major and minor number of each device, and each device identifier is
+separated by a colon (:). A valid specifier for devices 8,0 and 8,8 would then
+be: \fI8,0:8,8\fR.
.RE
.B \-e <\fIexe,...\fR>
analysed.
.RE
+.B \-h
+.br
+.B \-\-help
+.RS 4
+Shows a short summary of possible command line option
+.RE
+
+.B \-i <\fIinput name\fR>
+.br
+.B \-\-input\-file <\fIinput file\fR>
+.RS 4
+Specifies the input file to analyse. This should be a trace file produced
+by \fIblktrace\fR (8).
+.RE
+
.B \-I <\fIoutput name\fR>
.br
.B \-\-iostat=<\fIoutput name\fR>
name for each device.
.RE
+.B \-L <\fIfreq\fR>
+.br
+.B \-\-periodic\-latencies=<\fIfreq\fR>
+.RS 4
+The \-L option allows one to output periodic latency information for both
+Q2C and D2C latencies. The frequency specified will regulate how often
+an average latency is output -- a floating point value expressing seconds.
+.RE
+
+.B \-m <\fIoutput name\fR>
+.br
+.B \-\-seeks\-per\-second=<\fIoutput name\fR>
+.RS 4
+Trigger btt to output seeks-per-second information. The first column will
+contain a time value (seconds), and the second column will indicate the
+number of seeks per second at that point.
+.RE
+
.B \-M <\fIdev map\fR>
.br
.B \-\-dev\-maps=<\fIdev map\fR>
"sequences" \- showing the parts of each IO (Q, A, I/M, D, & C).
.RE
+.B \-P <\fIoutput name\fR>
+.br
+.B \-\-per\-io\-trees=<\fIoutput name\fR>
+.RS 4
+The \-P option will generate a file that contains a list of all IO
+"sequences" \- showing only the Q, D & C operation times. The D & C
+time values are separated from the Q time values with a vertical bar.
+.RE
+
.B \-q <\fIoutput name\fR>
.br
.B \-\-q2c\-latencies=<\fIoutput name\fR>
name for each device.
.RE
+.B \-Q <\fIoutput name\fR>
+.br
+.B \-\-active\-queue\-depth=<\fIoutput name\fR>
+.RS 4
+The \-Q option allows one to output data files showing the time stamp
+and the depth of active commands (those issued but not completed).
+.RE
+
+.B \-r
+.br
+.B \-\-no\-remaps
+.RS 4
+Ignore remap traces; older kernels did not implement the full remap
+PDU.
+.RE
+
.B \-s <\fIoutput name\fR>
.br
.B \-\-seeks=<\fIoutput name\fR>
if only \-T is specified, analysis stops after \-T's seconds.)
.RE
+.B \-u <\fIoutput name\fR>
+.br
+.B \-\-unplug\-hist=<\fIoutput name\fR>
+.RS 4
+This option instructs \fBbtt\fR to generate a data file containing histogram
+information for unplug traces on a per device basis. It shows how many
+times an unplug was hit with a specified number of IOs released. There are 21
+output values into the file, as follows:
+
+.RS 4
+a value of 0 represents 0..4 counts
+.br
+a value of 1 represents 5..9 counts
+.br
+a value of 2 represents 10..14 counts
+.br
+etc, until
+.br
+a value of 20 represents 100+ counts
+.br
+.RE
+
+The file name(s) generated use the text string passed as an argument for
+the prefix, followed by the device identifier in \fImajor,minor\fR
+form, with a \fI.dat\fR extension. For example, with \fI\-u
+up_hist\fR specified on the command line: \fIup_hist_008,032.dat\fR.
+.RE
+
+.B \-V
+.br
+.B \-\-version
+.RS 4
+Shows the version of btt.
+.RE
+
.B \-v
.br
.B \-\-verbose
Requests a more verbose output.
.RE
+.B \-X
+.br
+.B \-\-easy\-parse\-avgs
+.RS 4
+Provide data in an easy-to-parse form and write it to a file
+with .avg exentsion
+.RE
+
+.B \-z <\fIoutput name\fR>
+.br
+.B \-\-q2d\-latencies=<\fIoutput name\fR>
+.RS 4
+The \-z option allows one to output per\-IO Q2D latencies
+respectively. The supplied argument provides the basis for the output
+name for each device.
+.RE
+
+.B \-Z
+.br
+.B \-\-do\-active
+.RS 4
+The \-Z will output files containing data which can be plotted showing
+per\-device (and total system) I/O activity.
+.RE
+
.SH AUTHORS
-\fIblkparse\fR was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This
-man page was created from the \fIblktrace\fR documentation by Bas Zoetekouw.
+\fIbtt\fR was written by Alan D. Brunelle. This man page was created
+from the \fIblktrace\fR documentation by Bas Zoetekouw.
.SH "REPORTING BUGS"
/usr/share/common\-licenses/GPL\-2.
.SH "SEE ALSO"
-blktrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)
+The btt Users Guide, which can be found in /usr/share/doc/blktrace/btt.pdf
+.br
+bno_plot (1), blktrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)
projects / blktrace.git / blobdiff