doc/btreplay.8

   1 .TH BTREPLAY 8 "December  8, 2007" "blktrace git\-20071207142532" ""
   2
   3
   4 .SH NAME
   5 btreplay \- recreate IO loads recorded by blktrace
   6
   7
   8 .SH SYNOPSIS
   9 .B btreplay [ \fIoptions\fR ] <\fIdev\fR...>
  10
  11
  12 .SH DESCRIPTION
  13
  14 .P
  15 The \fIbtrecord\fR and \fIbtreplay\fR tools provide the ability to
  16 record and replay IOs captured by the \fIblktrace\fR utility. Attempts
  17 are made to maintain ordering, CPU mappings and time-separation of IOs.
  18
  19
  20 .P
  21 The \fIblktrace\fR utility provides the ability to collect detailed
  22 traces from the kernel for each IO processed by the block IO layer. The
  23 traces provide a complete timeline for each IO processed, including
  24 detailed information concerning when an IO was first received by the block
  25 IO layer \(em indicating the device, CPU number, time stamp, IO direction,
  26 sector number and IO size (number of sectors). Using this information,
  27 one is able to \fBreplay\fR the IO again on the same machine or another
  28 set up entirely.
  29
  30 .P
  31 The basic operating work-flow to replay IOs would be something like:
  32
  33 .IP \- 2
  34   Run \fIblktrace\fR to collect traces. Here you specify the
  35   device or devices that you wish to trace and later replay IOs upon. Note:
  36   the only traces you are interested in are \fBQUEUE\fR requests \(em
  37   thus, to save system resources (including storage for traces), one could
  38   specify the \fI-a queue\fR command line option to \fIblktrace\fR.
  39
  40 .IP \- 2
  41   While \fIblktrace\fR is running, you run the workload that you
  42   are interested in.
  43
  44 .IP \- 2
  45   When the work load has completed, you stop the \fIblktrace\fR
  46   utility (thus saving all traces over the complete workload).
  47
  48 .IP \- 2
  49   You extract the pertinent IO information from the traces saved by
  50   \fIblktrace\fR using the \fIbtrecord\fR utility. This will parse
  51   each trace file created by \fIblktrace\fR, and crafty IO descriptions
  52   to be used in the next phase of the workload processing.
  53
  54 .IP \- 2
  55   Once \fIbtrecord\fR has successfully created a series of data
  56   files to be processed, you can run the \fIbtreplay\fR utility which
  57   attempts to generate the same IOs seen during the sample workload phase.
  58
  59
  60 .SH OPTIONS
  61
  62 \-c <\fInum\fR>
  63 .br
  64 \-\-cpus=<\fInum\fR>
  65 .RS
  66 Set number of CPUs to use.
  67 .RE
  68
  69 \-d <\fIdir\fR>
  70 .br
  71 \-\-input\-directory=<\fIdir\fR>
  72 .RS
  73 Set input directory.
  74 This option requires a single parameter providing the directory
  75 name for where input files are to be found. The default directory is the
  76 current directory (\fI.\fR).
  77 .RE
  78
  79 \-F
  80 .br
  81 \-\-find\-records
  82 .RS
  83 Find record files automatically
  84 This option instructs \fIbtreplay\fR to go find all the record files in the
  85 directory specified (either via the \fI-d\fR option, or in the default
  86 directory (\fI.\fR).
  87 .RE
  88
  89 \-h
  90 .br
  91 \-\-help
  92 .RS
  93 Show help and exit.
  94 .RE
  95
  96 \-i <\fIbasename\fR>
  97 .br
  98 \-\-input\-base=<\fIbasename\fR>
  99 .RS
 100 Set base name for input files.
 101 Each input file has 3 fields:
 102 .IP 1. 3
 103  Device identifier (taken directly from the device name of the
 104  \fIblktrace\fR output file).
 105 .IP 2. 3
 106  \fIbtrecord\fR base name \(em by default ``replay''.
 107 .IP 3. 3
 108  The CPU number (again, taken directly from the
 109  \fIblktrace\fR output file name).
 110 .P
 111 This option requires a single parameter that will override the default name
 112 (replay), and replace it with the specified value.
 113 .RE
 114
 115 \-I <\fInum\fR>
 116 .br
 117 \-\-iterations=<\fInum\fR>
 118 .RS
 119 Set number of iterations to run.
 120 This option requires a single parameter which specifies the number of times
 121 to run through the input files. The default value is 1
 122 .RE
 123
 124 \-M <\fIfilename\fR>
 125 .br
 126 \-\-map\-devs=<\fIfilename\fR>
 127 .RS
 128 Specify device mappings.
 129 This option requires a single parameter which specifies the name of a
 130 file contain device mappings. The file must be very simply managed, with
 131 just two pieces of data per line:
 132
 133 .IP \- 2
 134   The device name on the recorded system (with the '\fI/dev/\fR'
 135   removed). Example: \fI/dev/sda\fR would just be \fIsda\fR.
 136
 137 .IP \- 2
 138   The device name on the replay system to use (again, without the
 139   '\fI/dev/\fR' path prepended).
 140
 141 .P
 142 An example file for when one would map devices \fI/dev/sda\fR and
 143 \fI/dev/sdb\fR on the recorded system to \fIdev/sdg\fR and
 144 \fIsdh\fR on the replay system would be:
 145
 146 .nf
 147 .IP
 148 sda sdg
 149 sdb sdh
 150 .fi
 151
 152 .P
 153 The only entries in the file that are allowed are these two element lines \(em
 154 we do not (yet?) support the notion of blank lines, or comment lines, or the
 155 like.
 156
 157 .P
 158 The utility allows for multiple \fI-M\fR options to be
 159 supplied on the command line.
 160 .RE
 161
 162 \-N
 163 .br
 164 \-\-no\-stalls
 165 .RS
 166 Disable pre-bunch stalls.
 167 When specified on the command line, all pre-bunch stall indicators will be
 168 ignored. IOs will be replayed without inter-bunch delays.
 169 .RE
 170
 171 \-x <\fIfactor\fR>
 172 .br
 173 \-\-acc\-factor=<\fIfactor\fR>
 174 .RS
 175 Specify acceleration factor. Default value is 1 (no acceleration).
 176 .RE
 177
 178 \-v
 179 .br
 180 \-\-verbose
 181 .RS
 182 Enable verbose output.
 183 When specified on the command line, this option instructs \fIbtreplay\fR
 184 to store information concerning each \fBstall\fR and IO operation
 185 performed by \fIbtreplay\fR. The name of each file so created will be
 186 the input file name used with an extension of \fI.rep\fR appended onto
 187 it. Thus, an input file of the name \fIsdab.replay.3\fR would generate a
 188 verbose output file with the name \fIsdab.replay.3.rep\fR in the
 189 directory specified for input files.
 190 .P
 191 In addition, \fIbtreplay\fR will also output to \fIstderr\fR the
 192 names of the input files being processed.
 193 .RE
 194
 195 \-V
 196 .br
 197 \-\-version
 198 .RS
 199 Show version number and exit.
 200 .RE
 201
 202 \-W
 203 .br
 204 \-\-write-enable
 205 .RS
 206 Enable writing during replay.
 207 As a precautionary measure, by default \fIbtreplay\fR will not
 208 process \fBwrite\fR requests. In order to enable \fIbtreplay\fR to
 209 actually \fBwrite\fR to devices one must explicitly specify the
 210 \fI\-W\fR option.
 211 .RE
 212
 213
 214 .SH AUTHORS
 215 \fIbtreplay\fR was written by Alan D. Brunelle.  This
 216 man page was created from the \fIbtreplay\fR documentation by Bas Zoetekouw.
 217
 218
 219 .SH "REPORTING BUGS"
 220 Report bugs to <linux\-btrace@vger.kernel.org>
 221
 222 .SH COPYRIGHT
 223 Copyright \(co 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott.
 224 .br
 225 This is free software.  You may redistribute copies of it under the terms of
 226 the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
 227 There is NO WARRANTY, to the extent permitted by law.
 228 .br
 229 This manual page was created for Debian by Bas Zoetekouw.  It was derived from
 230 the documentation provided by the authors and it may be used, distributed and
 231 modified under the terms of the GNU General Public License, version 2.
 232 .br
 233 On Debian systems, the text of the GNU General Public License can be found in
 234 /usr/share/common\-licenses/GPL\-2.
 235
 236 .SH "SEE ALSO"
 237 The full documentation for btreplay can be found in /usr/share/doc/blktrace on Debian systems.
 238 .br
 239 blktrace (8), blkparse (1), btrecord (8)
 240