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