|
Packit |
c4abd9 |
.TH BTREPLAY 8 "December 8, 2007" "blktrace git\-20071207142532" ""
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.SH NAME
|
|
Packit |
c4abd9 |
btreplay \- recreate IO loads recorded by blktrace
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.SH SYNOPSIS
|
|
Packit |
c4abd9 |
.B btreplay [ \fIoptions\fR ] <\fIdev\fR...>
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.SH DESCRIPTION
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.P
|
|
Packit |
c4abd9 |
The \fIbtrecord\fR and \fIbtreplay\fR tools provide the ability to
|
|
Packit |
c4abd9 |
record and replay IOs captured by the \fIblktrace\fR utility. Attempts
|
|
Packit |
c4abd9 |
are made to maintain ordering, CPU mappings and time-separation of IOs.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.P
|
|
Packit |
c4abd9 |
The \fIblktrace\fR utility provides the ability to collect detailed
|
|
Packit |
c4abd9 |
traces from the kernel for each IO processed by the block IO layer. The
|
|
Packit |
c4abd9 |
traces provide a complete timeline for each IO processed, including
|
|
Packit |
c4abd9 |
detailed information concerning when an IO was first received by the block
|
|
Packit |
c4abd9 |
IO layer \(em indicating the device, CPU number, time stamp, IO direction,
|
|
Packit |
c4abd9 |
sector number and IO size (number of sectors). Using this information,
|
|
Packit |
c4abd9 |
one is able to \fBreplay\fR the IO again on the same machine or another
|
|
Packit |
c4abd9 |
set up entirely.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.P
|
|
Packit |
c4abd9 |
The basic operating work-flow to replay IOs would be something like:
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.IP \- 2
|
|
Packit |
c4abd9 |
Run \fIblktrace\fR to collect traces. Here you specify the
|
|
Packit |
c4abd9 |
device or devices that you wish to trace and later replay IOs upon. Note:
|
|
Packit |
c4abd9 |
the only traces you are interested in are \fBQUEUE\fR requests \(em
|
|
Packit |
c4abd9 |
thus, to save system resources (including storage for traces), one could
|
|
Packit |
c4abd9 |
specify the \fI-a queue\fR command line option to \fIblktrace\fR.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.IP \- 2
|
|
Packit |
c4abd9 |
While \fIblktrace\fR is running, you run the workload that you
|
|
Packit |
c4abd9 |
are interested in.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.IP \- 2
|
|
Packit |
c4abd9 |
When the work load has completed, you stop the \fIblktrace\fR
|
|
Packit |
c4abd9 |
utility (thus saving all traces over the complete workload).
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.IP \- 2
|
|
Packit |
c4abd9 |
You extract the pertinent IO information from the traces saved by
|
|
Packit |
c4abd9 |
\fIblktrace\fR using the \fIbtrecord\fR utility. This will parse
|
|
Packit |
c4abd9 |
each trace file created by \fIblktrace\fR, and crafty IO descriptions
|
|
Packit |
c4abd9 |
to be used in the next phase of the workload processing.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.IP \- 2
|
|
Packit |
c4abd9 |
Once \fIbtrecord\fR has successfully created a series of data
|
|
Packit |
c4abd9 |
files to be processed, you can run the \fIbtreplay\fR utility which
|
|
Packit |
c4abd9 |
attempts to generate the same IOs seen during the sample workload phase.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.SH OPTIONS
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-c <\fInum\fR>
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-cpus=<\fInum\fR>
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Set number of CPUs to use.
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-d <\fIdir\fR>
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-input\-directory=<\fIdir\fR>
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Set input directory.
|
|
Packit |
c4abd9 |
This option requires a single parameter providing the directory
|
|
Packit |
c4abd9 |
name for where input files are to be found. The default directory is the
|
|
Packit |
c4abd9 |
current directory (\fI.\fR).
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-F
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-find\-records
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Find record files automatically
|
|
Packit |
c4abd9 |
This option instructs \fIbtreplay\fR to go find all the record files in the
|
|
Packit |
c4abd9 |
directory specified (either via the \fI-d\fR option, or in the default
|
|
Packit |
c4abd9 |
directory (\fI.\fR).
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-h
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-help
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Show help and exit.
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-i <\fIbasename\fR>
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-input\-base=<\fIbasename\fR>
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Set base name for input files.
|
|
Packit |
c4abd9 |
Each input file has 3 fields:
|
|
Packit |
c4abd9 |
.IP 1. 3
|
|
Packit |
c4abd9 |
Device identifier (taken directly from the device name of the
|
|
Packit |
c4abd9 |
\fIblktrace\fR output file).
|
|
Packit |
c4abd9 |
.IP 2. 3
|
|
Packit |
c4abd9 |
\fIbtrecord\fR base name \(em by default ``replay''.
|
|
Packit |
c4abd9 |
.IP 3. 3
|
|
Packit |
c4abd9 |
The CPU number (again, taken directly from the
|
|
Packit |
c4abd9 |
\fIblktrace\fR output file name).
|
|
Packit |
c4abd9 |
.P
|
|
Packit |
c4abd9 |
This option requires a single parameter that will override the default name
|
|
Packit |
c4abd9 |
(replay), and replace it with the specified value.
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-I <\fInum\fR>
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-iterations=<\fInum\fR>
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Set number of iterations to run.
|
|
Packit |
c4abd9 |
This option requires a single parameter which specifies the number of times
|
|
Packit |
c4abd9 |
to run through the input files. The default value is 1
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-M <\fIfilename\fR>
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-map\-devs=<\fIfilename\fR>
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Specify device mappings.
|
|
Packit |
c4abd9 |
This option requires a single parameter which specifies the name of a
|
|
Packit |
c4abd9 |
file contain device mappings. The file must be very simply managed, with
|
|
Packit |
c4abd9 |
just two pieces of data per line:
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.IP \- 2
|
|
Packit |
c4abd9 |
The device name on the recorded system (with the '\fI/dev/\fR'
|
|
Packit |
c4abd9 |
removed). Example: \fI/dev/sda\fR would just be \fIsda\fR.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.IP \- 2
|
|
Packit |
c4abd9 |
The device name on the replay system to use (again, without the
|
|
Packit |
c4abd9 |
'\fI/dev/\fR' path prepended).
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.P
|
|
Packit |
c4abd9 |
An example file for when one would map devices \fI/dev/sda\fR and
|
|
Packit |
c4abd9 |
\fI/dev/sdb\fR on the recorded system to \fIdev/sdg\fR and
|
|
Packit |
c4abd9 |
\fIsdh\fR on the replay system would be:
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.nf
|
|
Packit |
c4abd9 |
.IP
|
|
Packit |
c4abd9 |
sda sdg
|
|
Packit |
c4abd9 |
sdb sdh
|
|
Packit |
c4abd9 |
.fi
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.P
|
|
Packit |
c4abd9 |
The only entries in the file that are allowed are these two element lines \(em
|
|
Packit |
c4abd9 |
we do not (yet?) support the notion of blank lines, or comment lines, or the
|
|
Packit |
c4abd9 |
like.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.P
|
|
Packit |
c4abd9 |
The utility allows for multiple \fI-M\fR options to be
|
|
Packit |
c4abd9 |
supplied on the command line.
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-N
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-no\-stalls
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Disable pre-bunch stalls.
|
|
Packit |
c4abd9 |
When specified on the command line, all pre-bunch stall indicators will be
|
|
Packit |
c4abd9 |
ignored. IOs will be replayed without inter-bunch delays.
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-x <\fIfactor\fR>
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-acc\-factor=<\fIfactor\fR>
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Specify acceleration factor. Default value is 1 (no acceleration).
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-v
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-verbose
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Enable verbose output.
|
|
Packit |
c4abd9 |
When specified on the command line, this option instructs \fIbtreplay\fR
|
|
Packit |
c4abd9 |
to store information concerning each \fBstall\fR and IO operation
|
|
Packit |
c4abd9 |
performed by \fIbtreplay\fR. The name of each file so created will be
|
|
Packit |
c4abd9 |
the input file name used with an extension of \fI.rep\fR appended onto
|
|
Packit |
c4abd9 |
it. Thus, an input file of the name \fIsdab.replay.3\fR would generate a
|
|
Packit |
c4abd9 |
verbose output file with the name \fIsdab.replay.3.rep\fR in the
|
|
Packit |
c4abd9 |
directory specified for input files.
|
|
Packit |
c4abd9 |
.P
|
|
Packit |
c4abd9 |
In addition, \fIbtreplay\fR will also output to \fIstderr\fR the
|
|
Packit |
c4abd9 |
names of the input files being processed.
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-V
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-version
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Show version number and exit.
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
\-W
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
\-\-write-enable
|
|
Packit |
c4abd9 |
.RS
|
|
Packit |
c4abd9 |
Enable writing during replay.
|
|
Packit |
c4abd9 |
As a precautionary measure, by default \fIbtreplay\fR will not
|
|
Packit |
c4abd9 |
process \fBwrite\fR requests. In order to enable \fIbtreplay\fR to
|
|
Packit |
c4abd9 |
actually \fBwrite\fR to devices one must explicitly specify the
|
|
Packit |
c4abd9 |
\fI\-W\fR option.
|
|
Packit |
c4abd9 |
.RE
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.SH AUTHORS
|
|
Packit |
c4abd9 |
\fIbtreplay\fR was written by Alan D. Brunelle. This
|
|
Packit |
c4abd9 |
man page was created from the \fIbtreplay\fR documentation by Bas Zoetekouw.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.SH "REPORTING BUGS"
|
|
Packit |
c4abd9 |
Report bugs to <linux\-btrace@vger.kernel.org>
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.SH COPYRIGHT
|
|
Packit |
c4abd9 |
Copyright \(co 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott.
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
This is free software. You may redistribute copies of it under the terms of
|
|
Packit |
c4abd9 |
the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
|
|
Packit |
c4abd9 |
There is NO WARRANTY, to the extent permitted by law.
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
This manual page was created for Debian by Bas Zoetekouw. It was derived from
|
|
Packit |
c4abd9 |
the documentation provided by the authors and it may be used, distributed and
|
|
Packit |
c4abd9 |
modified under the terms of the GNU General Public License, version 2.
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
On Debian systems, the text of the GNU General Public License can be found in
|
|
Packit |
c4abd9 |
/usr/share/common\-licenses/GPL\-2.
|
|
Packit |
c4abd9 |
|
|
Packit |
c4abd9 |
.SH "SEE ALSO"
|
|
Packit |
c4abd9 |
The full documentation for btreplay can be found in /usr/share/doc/blktrace on Debian systems.
|
|
Packit |
c4abd9 |
.br
|
|
Packit |
c4abd9 |
blktrace (8), blkparse (1), btrecord (8)
|
|
Packit |
c4abd9 |
|