1 .TH BTRECORD 8 "December 8, 2007" "blktrace git\-20071207142532" ""
5 btrecord \- recreate IO loads recorded by blktrace
11 btrecord [ \fIoptions\fR ] <\fIdev\fR...>
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.
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
33 The basic operating work-flow to replay IOs would be something like:
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.
43 While \fIblktrace\fR is running, you run the workload that you
47 When the work load has completed, you stop the \fIblktrace\fR
48 utility (thus saving all traces over the complete workload).
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.
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.
66 \-\-input\-directory=<\fIdir\fR>
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).
76 \-\-output\-directory=<\fIdir\fR>
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).
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
105 Show version number and exit.
108 \-m <\fInanoseconds\fR>
110 \-\-max\-bunch\-time=<\fInanoseconds\fR>
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.
119 The default value is 10,000,000 nanoseconds (10 milliseconds).
124 \-\-max\-pkts=<\fInum\fR>
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.
131 The default value is 8, with a maximum value of up to 512 being supported.
136 \-\-output\-base=<\fIbasename\fR>
138 Set base name for output files.
139 Each output file has 3 fields:
141 Device identifier (taken directly from the device name of the
142 \fIblktrace\fR output file).
144 \fIbtrecord\fR base name \(em by default ``replay''.
146 The CPU number (again, taken directly from the
147 \fIblktrace\fR output file name).
149 This option requires a single parameter that will override the default name
150 (replay), and replace it with the specified value.
157 Enable verbose output.
158 This option will output some simple statistics at the end of a successful
159 run. Example output is:
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
168 The meaning of the columns is:
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.
173 The second field contains the total number of packets processed for each
176 The next field shows the number of packets eligible for replay.
178 The fourth field contains the total number of IO bunches.
180 The last field shows the average number of IOs per bunch recorded.
185 \fIbtrecord\fR was written by Alan D. Brunelle. This
186 man page was created from the \fIbtreplay\fR documentation by Bas Zoetekouw.
190 Report bugs to <linux\-btrace@vger.kernel.org>
193 Copyright \(co 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott.
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.
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.
203 On Debian systems, the text of the GNU General Public License can be found in
204 /usr/share/common\-licenses/GPL\-2.
207 The full documentation for btreplay can be found in /usr/share/doc/blktrace on Debian systems.
209 blktrace (8), blkparse (1), btreplay (8)