btreplay(8)

1BTREPLAY(8)                                                        BTREPLAY(8)
2
3
4

NAME

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

SYNOPSIS

11       btreplay [ options ] <dev...>
12
13
14

DESCRIPTION

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

OPTIONS

71       -c <num>
72       --cpus=<num>
73              Set number of CPUs to use.
74
75       -d <dir>
76       --input-directory=<dir>
77              Set  input  directory.   This option requires a single parameter
78              providing the directory name for where input  files  are  to  be
79              found. The default directory is the current directory (.).
80
81       -F
82       --find-records
83              Find  record  files automatically This option instructs btreplay
84              to go find all the  record  files  in  the  directory  specified
85              (either via the -d option, or in the default directory (.).
86
87       -h
88       --help
89              Show help and exit.
90
91       -i <basename>
92       --input-base=<basename>
93              Set base name for input files.  Each input file has 3 fields:
94
95              1.
96                  Device  identifier  (taken  directly from the device name of
97                 the
98                  blktrace output file).
99
100              2.
101                  btrecord base name — by default ``replay''.
102
103              3.
104                  The CPU number (again, taken directly from the
105                  blktrace output file name).
106
107              This option requires a single parameter that will  override  the
108              default name (replay), and replace it with the specified value.
109
110       -I <num>
111       --iterations=<num>
112              Set  number of iterations to run.  This option requires a single
113              parameter which specifies the number of times to run through the
114              input files. The default value is 1
115
116       -M <filename>
117       --map-devs=<filename>
118              Specify  device mappings.  This option requires a single parame‐
119              ter which specifies the name of a file contain device  mappings.
120              The  file  must  be very simply managed, with just two pieces of
121              data per line:
122
123
124              -
125                  The device name on the recorded system (with the '/dev/'
126                  removed). Example: /dev/sda would just be sda.
127
128
129              -
130                  The device name on the replay system to use (again,  without
131                the
132                  '/dev/' path prepended).
133
134
135              An  example  file  for  when  one would map devices /dev/sda and
136              /dev/sdb on the recorded system to dev/sdg and sdh on the replay
137              system would be:
138
139
140                     sda sdg
141                     sdb sdh
142
143
144              The only entries in the file that are allowed are these two ele‐
145              ment lines — we do not (yet?) support the notion of blank lines,
146              or comment lines, or the like.
147
148
149              The utility allows for multiple -M options to be supplied on the
150              command line.
151
152       -N
153       --no-stalls
154              Disable pre-bunch stalls.  When specified on the  command  line,
155              all  pre-bunch  stall  indicators  will  be ignored. IOs will be
156              replayed without inter-bunch delays.
157
158       -v
159       --verbose
160              Enable verbose output.  When specified on the command line, this
161              option  instructs  btreplay to store information concerning each
162              stall and IO operation performed by btreplay. The name  of  each
163              file  so created will be the input file name used with an exten‐
164              sion of .rep appended onto it. Thus, an input file of  the  name
165              sdab.replay.3 would generate a verbose output file with the name
166              sdab.replay.3.rep in the directory specified for input files.
167
168              In addition, btreplay will also output to stderr  the  names  of
169              the input files being processed.
170
171       -V
172       --version
173              Show version number and exit.
174
175       -W
176       --write-enable
177              Enable  writing  during  replay.  As a precautionary measure, by
178              default btreplay will not process write requests.  In  order  to
179              enable btreplay to actually write to devices one must explicitly
180              specify the -W option.
181
182
183

AUTHORS

185       btreplay was written by Alan D. Brunelle.  This man  page  was  created
186       from the btreplay documentation by Bas Zoetekouw.
187
188
189

REPORTING BUGS

191       Report bugs to <linux-btrace@vger.kernel.org>
192
193

COPYRIGHT

195       Copyright © 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott.
196       This  is  free  software.   You may redistribute copies of it under the
197       terms      of      the      GNU      General       Public       License
198       <http://www.gnu.org/licenses/gpl.html>.   There  is NO WARRANTY, to the
199       extent permitted by law.
200       This manual page was created for  Debian  by  Bas  Zoetekouw.   It  was
201       derived  from  the  documentation provided by the authors and it may be
202       used, distributed and modified under the terms of the GNU General  Pub‐
203       lic License, version 2.
204       On  Debian  systems,  the text of the GNU General Public License can be
205       found in /usr/share/common-licenses/GPL-2.
206
207