1BTRECORD(8)                                                        BTRECORD(8)
2
3
4

NAME

6       btrecord - recreate IO loads recorded by blktrace
7
8
9

SYNOPSIS

11       Usage:
12
13       btrecord [ options ] <dev...>
14
15
16

DESCRIPTION

18       The  btrecord  and  btreplay  tools  provide  the ability to record and
19       replay IOs captured by the blktrace utility. Attempts are made to main‐
20       tain ordering, CPU mappings and time-separation of IOs.
21
22
23
24       The  blktrace  utility  provides the ability to collect detailed traces
25       from the kernel for each IO processed by the block IO layer. The traces
26       provide  a  complete timeline for each IO processed, including detailed
27       information concerning when an IO was first received by  the  block  IO
28       layer  —  indicating  the device, CPU number, time stamp, IO direction,
29       sector number and IO size (number of sectors). Using this  information,
30       one  is  able to replay the IO again on the same machine or another set
31       up entirely.
32
33
34       The basic operating work-flow to replay IOs would be something like:
35
36
37       -
38           Run blktrace to collect traces. Here you specify the
39           device or devices that you wish to trace and later replay IOs upon.
40         Note:
41           the only traces you are interested in are QUEUE requests —
42           thus,  to save system resources (including storage for traces), one
43         could
44           specify the -a queue command line option to blktrace.
45
46
47       -
48           While blktrace is running, you run the workload that you
49           are interested in.
50
51
52       -
53           When the work load has completed, you stop the blktrace
54           utility (thus saving all traces over the complete workload).
55
56
57       -
58           You extract the pertinent IO information from the traces saved by
59           blktrace using the btrecord utility. This will parse
60           each trace file created by blktrace, and crafty IO descriptions
61           to be used in the next phase of the workload processing.
62
63
64       -
65           Once btrecord has successfully created a series of data
66           files to be processed, you can run the btreplay utility which
67           attempts to generate the same IOs seen during the  sample  workload
68         phase.
69
70
71

OPTIONS

73       -d <dir>
74       --input-directory=<dir>
75              Set  input  directory.   This option requires a single parameter
76              providing the directory name for where input  files  are  to  be
77              found. The default directory is the current directory (.).
78
79       -D <dir>
80       --output-directory=<dir>
81              Set  output  directory.  This option requires a single parameter
82              providing the directory name for where output files  are  to  be
83              found. The default directory is the current directory (.).
84
85       -F
86       --find-traces
87              Find trace files automatically This option instructs btreplay to
88              go find all the trace files in the directory  specified  (either
89              via the -d option, or in the default directory (.).
90
91       -h
92       --help
93              Show help and exit.
94
95       -V
96       --version
97              Show version number and exit.
98
99       -m <nanoseconds>
100       --max-bunch-time=<nanoseconds>
101              The  -m  option  requires  a single parameter which specifies an
102              amount of time (in nanoseconds) to include in any one  bunch  of
103              IOs that are to be processed. The smaller the value, the smaller
104              the number of IOs processed at one time —  perhaps  yielding  in
105              more  realistic  replay.   However,  after  a  certain point the
106              amount of overhead per  bunch  may  result  in  additional  real
107              replay time, thus yielding less accurate replay times.
108
109              The default value is 10,000,000 nanoseconds (10 milliseconds).
110
111       -M <num>
112       --max-pkts=<num>
113              Set maximum number of packets per bunch.  The -M option requires
114              a single parameter which specifies the maximum number of IOs  to
115              store  in  a single bunch. As with the -m option, smaller values
116              may or may not yield more accurate replay times.
117
118              The default value is 8, with a maximum value of up to 512  being
119              supported.
120
121       -o <basename>
122       --output-base=<basename>
123              Set base name for output files.  Each output file has 3 fields:
124
125              1.
126                  Device  identifier  (taken  directly from the device name of
127                 the
128                  blktrace output file).
129
130              2.
131                  btrecord base name — by default ``replay''.
132
133              3.
134                  The CPU number (again, taken directly from the
135                  blktrace output file name).
136
137              This option requires a single parameter that will  override  the
138              default name (replay), and replace it with the specified value.
139
140       -v
141       --verbose
142              Enable verbose output.  This option will output some simple sta‐
143              tistics at the end of a successful run.  Example output is:
144
145              sdab:0: 580661 pkts (tot), 126030 pkts (replay), 89809 bunches, 1.4 pkts/bunch
146              sdab:1: 2559775 pkts (tot), 430172 pkts (replay), 293029 bunches, 1.5 pkts/bunch
147              sdab:2: 653559 pkts (tot), 136522 pkts (replay), 102288 bunches, 1.3 pkts/bunch
148              sdab:3: 474773 pkts (tot), 117849 pkts (replay), 69572 bunches, 1.7 pkts/bunch
149
150              The meaning of the columns is:
151
152              1.
153                   The first field contains the device name  and  CPU  identi‐
154                 fier. Thus:
155                   sdab:0: means the device sdab and traces on CPU 0.
156
157              2.
158                   The  second field contains the total number of packets pro‐
159                 cessed for each
160                   device file.
161
162              3.
163                   The next field shows the number  of  packets  eligible  for
164                 replay.
165
166              4.
167                   The fourth field contains the total number of IO bunches.
168
169              5.
170                   The  last  field  shows the average number of IOs per bunch
171                 recorded.
172
173
174

AUTHORS

176       btrecord was written by Alan D. Brunelle.  This man  page  was  created
177       from the btreplay documentation by Bas Zoetekouw.
178
179
180

REPORTING BUGS

182       Report bugs to <linux-btrace@vger.kernel.org>
183
184
186       Copyright © 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott.
187       This  is  free  software.   You may redistribute copies of it under the
188       terms      of      the      GNU      General       Public       License
189       <http://www.gnu.org/licenses/gpl.html>.   There  is NO WARRANTY, to the
190       extent permitted by law.
191       This manual page was created for  Debian  by  Bas  Zoetekouw.   It  was
192       derived  from  the  documentation provided by the authors and it may be
193       used, distributed and modified under the terms of the GNU General  Pub‐
194       lic License, version 2.
195       On  Debian  systems,  the text of the GNU General Public License can be
196       found in /usr/share/common-licenses/GPL-2.
197
198

SEE ALSO

200       The full documentation for btreplay can be found in /usr/share/doc/blk‐
201       trace on Debian systems.
202       blktrace (8), blkparse (1), btreplay (8)
203
204
205
206
207blktrace git-20071207142532    December  8, 2007                   BTRECORD(8)
Impressum