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       -x <factor>
159       --acc-factor=<factor>
160              Specify acceleration factor. Default value is  1  (no  accelera‐
161              tion).
162
163       -v
164       --verbose
165              Enable verbose output.  When specified on the command line, this
166              option instructs btreplay to store information  concerning  each
167              stall  and  IO operation performed by btreplay. The name of each
168              file so created will be the input file name used with an  exten‐
169              sion  of  .rep appended onto it. Thus, an input file of the name
170              sdab.replay.3 would generate a verbose output file with the name
171              sdab.replay.3.rep in the directory specified for input files.
172
173              In  addition,  btreplay  will also output to stderr the names of
174              the input files being processed.
175
176       -V
177       --version
178              Show version number and exit.
179
180       -W
181       --write-enable
182              Enable writing during replay.  As a  precautionary  measure,  by
183              default  btreplay  will  not process write requests. In order to
184              enable btreplay to actually write to devices one must explicitly
185              specify the -W option.
186
187
188

AUTHORS

190       btreplay  was  written  by Alan D. Brunelle.  This man page was created
191       from the btreplay documentation by Bas Zoetekouw.
192
193
194

REPORTING BUGS

196       Report bugs to <linux-btrace@vger.kernel.org>
197
198

COPYRIGHT

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