doc/btrecord.8

   1 .TH BTRECORD 8 "December  8, 2007" "blktrace git\-20071207142532" ""
   2
   3
   4 .SH NAME
   5 btrecord \- recreate IO loads recorded by blktrace
   6
   7
   8 .SH SYNOPSIS
   9 .B Usage:
  10
  11 btrecord [ \fIoptions\fR ] <\fIdev\fR...>
  12
  13
  14 .SH DESCRIPTION
  15
  16 .P
  17 The \fIbtrecord\fR and \fIbtreplay\fR tools provide the ability to
  18 record and replay IOs captured by the \fIblktrace\fR utility. Attempts
  19 are made to maintain ordering, CPU mappings and time-separation of IOs.
  20
  21
  22 .P
  23 The \fIblktrace\fR utility provides the ability to collect detailed
  24 traces from the kernel for each IO processed by the block IO layer. The
  25 traces provide a complete timeline for each IO processed, including
  26 detailed information concerning when an IO was first received by the block
  27 IO layer \(em indicating the device, CPU number, time stamp, IO direction,
  28 sector number and IO size (number of sectors). Using this information,
  29 one is able to \fBreplay\fR the IO again on the same machine or another
  30 set up entirely.
  31
  32 .P
  33 The basic operating work-flow to replay IOs would be something like:
  34
  35 .IP \- 2
  36   Run \fIblktrace\fR to collect traces. Here you specify the
  37   device or devices that you wish to trace and later replay IOs upon. Note:
  38   the only traces you are interested in are \fBQUEUE\fR requests \(em
  39   thus, to save system resources (including storage for traces), one could
  40   specify the \fI-a queue\fR command line option to \fIblktrace\fR.
  41
  42 .IP \- 2
  43   While \fIblktrace\fR is running, you run the workload that you
  44   are interested in.
  45
  46 .IP \- 2
  47   When the work load has completed, you stop the \fIblktrace\fR
  48   utility (thus saving all traces over the complete workload).
  49
  50 .IP \- 2
  51   You extract the pertinent IO information from the traces saved by
  52   \fIblktrace\fR using the \fIbtrecord\fR utility. This will parse
  53   each trace file created by \fIblktrace\fR, and crafty IO descriptions
  54   to be used in the next phase of the workload processing.
  55
  56 .IP \- 2
  57   Once \fIbtrecord\fR has successfully created a series of data
  58   files to be processed, you can run the \fIbtreplay\fR utility which
  59   attempts to generate the same IOs seen during the sample workload phase.
  60
  61
  62 .SH OPTIONS
  63
  64 \-d <\fIdir\fR>
  65 .br
  66 \-\-input\-directory=<\fIdir\fR>
  67 .RS
  68 Set input directory.
  69 This option requires a single parameter providing the directory
  70 name for where input files are to be found. The default directory is the
  71 current directory (\fI.\fR).
  72 .RE
  73
  74 \-D <\fIdir\fR>
  75 .br
  76 \-\-output\-directory=<\fIdir\fR>
  77 .RS
  78 Set output directory.
  79 This option requires a single parameter providing the directory
  80 name for where output files are to be found. The default directory is the
  81 current directory (\fI.\fR).
  82 .RE
  83
  84 \-F
  85 .br
  86 \-\-find\-traces
  87 .RS
  88 Find trace files automatically
  89 This option instructs \fIbtreplay\fR to go find all the trace files in the
  90 directory specified (either via the \fI-d\fR option, or in the default
  91 directory (\fI.\fR).
  92 .RE
  93
  94 \-h
  95 .br
  96 \-\-help
  97 .RS
  98 Show help and exit.
  99 .RE
 100
 101 \-V
 102 .br
 103 \-\-version
 104 .RS
 105 Show version number and exit.
 106 .RE
 107
 108 \-m <\fInanoseconds\fR>
 109 .br
 110 \-\-max\-bunch\-time=<\fInanoseconds\fR>
 111 .RS
 112 The \fI\-m\fR option requires a single parameter which specifies an
 113 amount of time (in nanoseconds) to include in any one bunch of IOs that
 114 are to be processed. The smaller the value, the smaller the number of
 115 IOs processed at one time \(em perhaps yielding in more realistic replay.
 116 However, after a certain point the amount of overhead per bunch may result
 117 in additional real replay time, thus yielding less accurate replay times.
 118 .P
 119 The default value is 10,000,000 nanoseconds (10 milliseconds).
 120 .RE
 121
 122 \-M <\fInum\fR>
 123 .br
 124 \-\-max\-pkts=<\fInum\fR>
 125 .RS
 126 Set maximum number of packets per bunch.
 127 The \fI\-M\fR option requires a single parameter which specifies the
 128 maximum number of IOs to store in a single bunch. As with the \fI\-m\fR
 129 option, smaller values may or may not yield more accurate replay times.
 130
 131 The default value is 8, with a maximum value of up to 512 being supported.
 132 .RE
 133
 134 \-o <\fIbasename\fR>
 135 .br
 136 \-\-output\-base=<\fIbasename\fR>
 137 .RS
 138 Set base name for output files.
 139 Each output file has 3 fields:
 140 .IP 1. 3
 141  Device identifier (taken directly from the device name of the
 142  \fIblktrace\fR output file).
 143 .IP 2. 3
 144  \fIbtrecord\fR base name \(em by default ``replay''.
 145 .IP 3. 3
 146  The CPU number (again, taken directly from the
 147  \fIblktrace\fR output file name).
 148 .P
 149 This option requires a single parameter that will override the default name
 150 (replay), and replace it with the specified value.
 151 .RE
 152
 153 \-v
 154 .br
 155 \-\-verbose
 156 .RS
 157 Enable verbose output.
 158 This option will output some simple statistics at the end of a successful
 159 run.  Example output is:
 160 .nf
 161 .P
 162 sdab:0: 580661 pkts (tot), 126030 pkts (replay), 89809 bunches, 1.4 pkts/bunch
 163 sdab:1: 2559775 pkts (tot), 430172 pkts (replay), 293029 bunches, 1.5 pkts/bunch
 164 sdab:2: 653559 pkts (tot), 136522 pkts (replay), 102288 bunches, 1.3 pkts/bunch
 165 sdab:3: 474773 pkts (tot), 117849 pkts (replay), 69572 bunches, 1.7 pkts/bunch
 166 .fi
 167 .P
 168 The meaning of the columns is:
 169 .IP 1. 3
 170   The first field contains the device name and CPU identifier. Thus:
 171   \fIsdab:0:\fR means the device \fIsdab\fR and traces on CPU 0.
 172 .IP 2.
 173   The second field contains the total number of packets processed for each
 174   device file.
 175 .IP 3.
 176   The next field shows the number of packets eligible for replay.
 177 .IP 4.
 178   The fourth field contains the total number of IO bunches.
 179 .IP 5.
 180   The last field shows the average number of IOs per bunch recorded.
 181 .RE
 182
 183
 184 .SH AUTHORS
 185 \fIbtrecord\fR was written by Alan D. Brunelle.  This
 186 man page was created from the \fIbtreplay\fR documentation by Bas Zoetekouw.
 187
 188
 189 .SH "REPORTING BUGS"
 190 Report bugs to <linux\-btrace@vger.kernel.org>
 191
 192 .SH COPYRIGHT
 193 Copyright \(co 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott.
 194 .br
 195 This is free software.  You may redistribute copies of it under the terms of
 196 the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
 197 There is NO WARRANTY, to the extent permitted by law.
 198 .br
 199 This manual page was created for Debian by Bas Zoetekouw.  It was derived from
 200 the documentation provided by the authors and it may be used, distributed and
 201 modified under the terms of the GNU General Public License, version 2.
 202 .br
 203 On Debian systems, the text of the GNU General Public License can be found in
 204 /usr/share/common\-licenses/GPL\-2.
 205
 206 .SH "SEE ALSO"
 207 The full documentation for btreplay can be found in /usr/share/doc/blktrace on Debian systems.
 208 .br
 209 blktrace (8), blkparse (1), btreplay (8)
 210