Commit | Line | Data |
---|---|---|
967492e8 | 1 | .TH BTREPLAY 8 "December 8, 2007" "blktrace git\-20071207142532" "" |
a84a97fd BZ |
2 | |
3 | ||
4 | .SH NAME | |
5 | btreplay \- recreate IO loads recorded by blktrace | |
6 | ||
7 | ||
8 | .SH SYNOPSIS | |
fbdf23ec | 9 | .B btreplay [ \fIoptions\fR ] <\fIdev\fR...> |
a84a97fd BZ |
10 | |
11 | ||
12 | .SH DESCRIPTION | |
13 | ||
14 | .P | |
15 | The \fIbtrecord\fR and \fIbtreplay\fR tools provide the ability to | |
16 | record and replay IOs captured by the \fIblktrace\fR utility. Attempts | |
17 | are made to maintain ordering, CPU mappings and time-separation of IOs. | |
18 | ||
19 | ||
20 | .P | |
21 | The \fIblktrace\fR utility provides the ability to collect detailed | |
22 | traces from the kernel for each IO processed by the block IO layer. The | |
23 | traces provide a complete timeline for each IO processed, including | |
24 | detailed information concerning when an IO was first received by the block | |
25 | IO layer \(em indicating the device, CPU number, time stamp, IO direction, | |
26 | sector number and IO size (number of sectors). Using this information, | |
27 | one is able to \fBreplay\fR the IO again on the same machine or another | |
28 | set up entirely. | |
29 | ||
30 | .P | |
31 | The basic operating work-flow to replay IOs would be something like: | |
32 | ||
33 | .IP \- 2 | |
34 | Run \fIblktrace\fR to collect traces. Here you specify the | |
35 | device or devices that you wish to trace and later replay IOs upon. Note: | |
36 | the only traces you are interested in are \fBQUEUE\fR requests \(em | |
37 | thus, to save system resources (including storage for traces), one could | |
38 | specify the \fI-a queue\fR command line option to \fIblktrace\fR. | |
39 | ||
40 | .IP \- 2 | |
41 | While \fIblktrace\fR is running, you run the workload that you | |
42 | are interested in. | |
43 | ||
44 | .IP \- 2 | |
45 | When the work load has completed, you stop the \fIblktrace\fR | |
46 | utility (thus saving all traces over the complete workload). | |
47 | ||
48 | .IP \- 2 | |
49 | You extract the pertinent IO information from the traces saved by | |
50 | \fIblktrace\fR using the \fIbtrecord\fR utility. This will parse | |
51 | each trace file created by \fIblktrace\fR, and crafty IO descriptions | |
52 | to be used in the next phase of the workload processing. | |
53 | ||
54 | .IP \- 2 | |
55 | Once \fIbtrecord\fR has successfully created a series of data | |
56 | files to be processed, you can run the \fIbtreplay\fR utility which | |
57 | attempts to generate the same IOs seen during the sample workload phase. | |
58 | ||
59 | ||
60 | .SH OPTIONS | |
61 | ||
62 | \-c <\fInum\fR> | |
63 | .br | |
64 | \-\-cpus=<\fInum\fR> | |
65 | .RS | |
66 | Set number of CPUs to use. | |
67 | .RE | |
68 | ||
69 | \-d <\fIdir\fR> | |
70 | .br | |
71 | \-\-input\-directory=<\fIdir\fR> | |
72 | .RS | |
73 | Set input directory. | |
74 | This option requires a single parameter providing the directory | |
75 | name for where input files are to be found. The default directory is the | |
76 | current directory (\fI.\fR). | |
77 | .RE | |
78 | ||
79 | \-F | |
80 | .br | |
81 | \-\-find\-records | |
82 | .RS | |
83 | Find record files automatically | |
84 | This option instructs \fIbtreplay\fR to go find all the record files in the | |
85 | directory specified (either via the \fI-d\fR option, or in the default | |
86 | directory (\fI.\fR). | |
87 | .RE | |
88 | ||
89 | \-h | |
90 | .br | |
91 | \-\-help | |
92 | .RS | |
93 | Show help and exit. | |
94 | .RE | |
95 | ||
96 | \-i <\fIbasename\fR> | |
97 | .br | |
98 | \-\-input\-base=<\fIbasename\fR> | |
99 | .RS | |
100 | Set base name for input files. | |
101 | Each input file has 3 fields: | |
102 | .IP 1. 3 | |
103 | Device identifier (taken directly from the device name of the | |
104 | \fIblktrace\fR output file). | |
105 | .IP 2. 3 | |
106 | \fIbtrecord\fR base name \(em by default ``replay''. | |
107 | .IP 3. 3 | |
108 | The CPU number (again, taken directly from the | |
109 | \fIblktrace\fR output file name). | |
110 | .P | |
111 | This option requires a single parameter that will override the default name | |
112 | (replay), and replace it with the specified value. | |
113 | .RE | |
114 | ||
115 | \-I <\fInum\fR> | |
116 | .br | |
117 | \-\-iterations=<\fInum\fR> | |
118 | .RS | |
119 | Set number of iterations to run. | |
120 | This option requires a single parameter which specifies the number of times | |
121 | to run through the input files. The default value is 1 | |
122 | .RE | |
123 | ||
124 | \-M <\fIfilename\fR> | |
125 | .br | |
126 | \-\-map\-devs=<\fIfilename\fR> | |
127 | .RS | |
128 | Specify device mappings. | |
fbdf23ec | 129 | This option requires a single parameter which specifies the name of a |
a84a97fd BZ |
130 | file contain device mappings. The file must be very simply managed, with |
131 | just two pieces of data per line: | |
132 | ||
133 | .IP \- 2 | |
134 | The device name on the recorded system (with the '\fI/dev/\fR' | |
135 | removed). Example: \fI/dev/sda\fR would just be \fIsda\fR. | |
136 | ||
137 | .IP \- 2 | |
138 | The device name on the replay system to use (again, without the | |
139 | '\fI/dev/\fR' path prepended). | |
140 | ||
141 | .P | |
142 | An example file for when one would map devices \fI/dev/sda\fR and | |
143 | \fI/dev/sdb\fR on the recorded system to \fIdev/sdg\fR and | |
144 | \fIsdh\fR on the replay system would be: | |
145 | ||
146 | .nf | |
147 | .IP | |
148 | sda sdg | |
149 | sdb sdh | |
150 | .fi | |
151 | ||
152 | .P | |
153 | The only entries in the file that are allowed are these two element lines \(em | |
154 | we do not (yet?) support the notion of blank lines, or comment lines, or the | |
155 | like. | |
156 | ||
157 | .P | |
158 | The utility allows for multiple \fI-M\fR options to be | |
159 | supplied on the command line. | |
160 | .RE | |
161 | ||
162 | \-N | |
163 | .br | |
164 | \-\-no\-stalls | |
165 | .RS | |
166 | Disable pre-bunch stalls. | |
167 | When specified on the command line, all pre-bunch stall indicators will be | |
168 | ignored. IOs will be replayed without inter-bunch delays. | |
169 | .RE | |
170 | ||
b86071c5 ES |
171 | \-x <\fIfactor\fR> |
172 | .br | |
173 | \-\-acc\-factor=<\fIfactor\fR> | |
174 | .RS | |
175 | Specify acceleration factor. Default value is 1 (no acceleration). | |
176 | .RE | |
177 | ||
a84a97fd BZ |
178 | \-v |
179 | .br | |
180 | \-\-verbose | |
181 | .RS | |
182 | Enable verbose output. | |
183 | When specified on the command line, this option instructs \fIbtreplay\fR | |
184 | to store information concerning each \fBstall\fR and IO operation | |
185 | performed by \fIbtreplay\fR. The name of each file so created will be | |
186 | the input file name used with an extension of \fI.rep\fR appended onto | |
187 | it. Thus, an input file of the name \fIsdab.replay.3\fR would generate a | |
188 | verbose output file with the name \fIsdab.replay.3.rep\fR in the | |
189 | directory specified for input files. | |
190 | .P | |
191 | In addition, \fIbtreplay\fR will also output to \fIstderr\fR the | |
192 | names of the input files being processed. | |
193 | .RE | |
194 | ||
195 | \-V | |
196 | .br | |
197 | \-\-version | |
198 | .RS | |
199 | Show version number and exit. | |
200 | .RE | |
201 | ||
202 | \-W | |
203 | .br | |
204 | \-\-write-enable | |
205 | .RS | |
206 | Enable writing during replay. | |
fbdf23ec ES |
207 | As a precautionary measure, by default \fIbtreplay\fR will not |
208 | process \fBwrite\fR requests. In order to enable \fIbtreplay\fR to | |
a84a97fd BZ |
209 | actually \fBwrite\fR to devices one must explicitly specify the |
210 | \fI\-W\fR option. | |
211 | .RE | |
212 | ||
213 | ||
214 | .SH AUTHORS | |
215 | \fIbtreplay\fR was written by Alan D. Brunelle. This | |
216 | man page was created from the \fIbtreplay\fR documentation by Bas Zoetekouw. | |
217 | ||
218 | ||
219 | .SH "REPORTING BUGS" | |
220 | Report bugs to <linux\-btrace@vger.kernel.org> | |
221 | ||
222 | .SH COPYRIGHT | |
223 | Copyright \(co 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott. | |
224 | .br | |
225 | This is free software. You may redistribute copies of it under the terms of | |
226 | the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. | |
227 | There is NO WARRANTY, to the extent permitted by law. | |
228 | .br | |
229 | This manual page was created for Debian by Bas Zoetekouw. It was derived from | |
230 | the documentation provided by the authors and it may be used, distributed and | |
231 | modified under the terms of the GNU General Public License, version 2. | |
232 | .br | |
233 | On Debian systems, the text of the GNU General Public License can be found in | |
234 | /usr/share/common\-licenses/GPL\-2. | |
235 | ||
236 | .SH "SEE ALSO" | |
237 | The full documentation for btreplay can be found in /usr/share/doc/blktrace on Debian systems. | |
238 | .br | |
239 | blktrace (8), blkparse (1), btrecord (8) | |
240 |