Commit | Line | Data |
---|---|---|
fbdf23ec | 1 | .TH BTRECORD 8 "December 8, 2007" "blktrace git\-20071207142532" "" |
a84a97fd BZ |
2 | |
3 | ||
4 | .SH NAME | |
5 | btrecord \- recreate IO loads recorded by blktrace | |
6 | ||
7 | ||
8 | .SH SYNOPSIS | |
9 | .B Usage: | |
10 | ||
11 | btrecord [ \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 | \-d <\fIdir\fR> | |
65 | .br | |
66 | \-\-input\-directory=<\fIdir\fR> | |
67 | .RS | |
68 | Set input directory. | |
69 | This option requires a single parameter providing the directory | |
70 | name for where input files are to be found. The default directory is the | |
71 | current directory (\fI.\fR). | |
72 | .RE | |
73 | ||
74 | \-D <\fIdir\fR> | |
75 | .br | |
76 | \-\-output\-directory=<\fIdir\fR> | |
77 | .RS | |
78 | Set output directory. | |
79 | This option requires a single parameter providing the directory | |
80 | name for where output files are to be found. The default directory is the | |
81 | current directory (\fI.\fR). | |
82 | .RE | |
83 | ||
84 | \-F | |
85 | .br | |
86 | \-\-find\-traces | |
87 | .RS | |
88 | Find trace files automatically | |
89 | This option instructs \fIbtreplay\fR to go find all the trace files in the | |
90 | directory specified (either via the \fI-d\fR option, or in the default | |
91 | directory (\fI.\fR). | |
92 | .RE | |
93 | ||
94 | \-h | |
95 | .br | |
96 | \-\-help | |
97 | .RS | |
98 | Show help and exit. | |
99 | .RE | |
100 | ||
101 | \-V | |
102 | .br | |
103 | \-\-version | |
104 | .RS | |
105 | Show version number and exit. | |
106 | .RE | |
107 | ||
fbdf23ec | 108 | \-m <\fInanoseconds\fR> |
a84a97fd | 109 | .br |
4a197d19 | 110 | \-\-max\-bunch\-time=<\fInanoseconds\fR> |
a84a97fd BZ |
111 | .RS |
112 | The \fI\-m\fR option requires a single parameter which specifies an | |
113 | amount of time (in nanoseconds) to include in any one bunch of IOs that | |
114 | are to be processed. The smaller the value, the smaller the number of | |
115 | IOs processed at one time \(em perhaps yielding in more realistic replay. | |
116 | However, after a certain point the amount of overhead per bunch may result | |
fbdf23ec | 117 | in additional real replay time, thus yielding less accurate replay times. |
a84a97fd BZ |
118 | .P |
119 | The default value is 10,000,000 nanoseconds (10 milliseconds). | |
120 | .RE | |
121 | ||
122 | \-M <\fInum\fR> | |
123 | .br | |
306a8ee9 | 124 | \-\-max\-pkts=<\fInum\fR> |
a84a97fd BZ |
125 | .RS |
126 | Set maximum number of packets per bunch. | |
127 | The \fI\-M\fR option requires a single parameter which specifies the | |
128 | maximum number of IOs to store in a single bunch. As with the \fI\-m\fR | |
129 | option, smaller values may or may not yield more accurate replay times. | |
130 | ||
131 | The default value is 8, with a maximum value of up to 512 being supported. | |
132 | .RE | |
133 | ||
134 | \-o <\fIbasename\fR> | |
135 | .br | |
136 | \-\-output\-base=<\fIbasename\fR> | |
137 | .RS | |
138 | Set base name for output files. | |
139 | Each output file has 3 fields: | |
140 | .IP 1. 3 | |
141 | Device identifier (taken directly from the device name of the | |
142 | \fIblktrace\fR output file). | |
143 | .IP 2. 3 | |
144 | \fIbtrecord\fR base name \(em by default ``replay''. | |
145 | .IP 3. 3 | |
146 | The CPU number (again, taken directly from the | |
147 | \fIblktrace\fR output file name). | |
148 | .P | |
149 | This option requires a single parameter that will override the default name | |
150 | (replay), and replace it with the specified value. | |
151 | .RE | |
152 | ||
153 | \-v | |
154 | .br | |
155 | \-\-verbose | |
156 | .RS | |
157 | Enable verbose output. | |
158 | This option will output some simple statistics at the end of a successful | |
159 | run. Example output is: | |
160 | .nf | |
161 | .P | |
162 | sdab:0: 580661 pkts (tot), 126030 pkts (replay), 89809 bunches, 1.4 pkts/bunch | |
163 | sdab:1: 2559775 pkts (tot), 430172 pkts (replay), 293029 bunches, 1.5 pkts/bunch | |
164 | sdab:2: 653559 pkts (tot), 136522 pkts (replay), 102288 bunches, 1.3 pkts/bunch | |
165 | sdab:3: 474773 pkts (tot), 117849 pkts (replay), 69572 bunches, 1.7 pkts/bunch | |
166 | .fi | |
167 | .P | |
168 | The meaning of the columns is: | |
169 | .IP 1. 3 | |
fbdf23ec | 170 | The first field contains the device name and CPU identifier. Thus: |
a84a97fd BZ |
171 | \fIsdab:0:\fR means the device \fIsdab\fR and traces on CPU 0. |
172 | .IP 2. | |
173 | The second field contains the total number of packets processed for each | |
174 | device file. | |
175 | .IP 3. | |
176 | The next field shows the number of packets eligible for replay. | |
177 | .IP 4. | |
178 | The fourth field contains the total number of IO bunches. | |
179 | .IP 5. | |
180 | The last field shows the average number of IOs per bunch recorded. | |
181 | .RE | |
182 | ||
183 | ||
184 | .SH AUTHORS | |
185 | \fIbtrecord\fR was written by Alan D. Brunelle. This | |
186 | man page was created from the \fIbtreplay\fR documentation by Bas Zoetekouw. | |
187 | ||
188 | ||
189 | .SH "REPORTING BUGS" | |
190 | Report bugs to <linux\-btrace@vger.kernel.org> | |
191 | ||
192 | .SH COPYRIGHT | |
193 | Copyright \(co 2007 Alan D. Brunelle, Alan D. Brunelle and Nathan Scott. | |
194 | .br | |
195 | This is free software. You may redistribute copies of it under the terms of | |
196 | the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. | |
197 | There is NO WARRANTY, to the extent permitted by law. | |
198 | .br | |
199 | This manual page was created for Debian by Bas Zoetekouw. It was derived from | |
200 | the documentation provided by the authors and it may be used, distributed and | |
201 | modified under the terms of the GNU General Public License, version 2. | |
202 | .br | |
203 | On Debian systems, the text of the GNU General Public License can be found in | |
204 | /usr/share/common\-licenses/GPL\-2. | |
205 | ||
206 | .SH "SEE ALSO" | |
207 | The full documentation for btreplay can be found in /usr/share/doc/blktrace on Debian systems. | |
208 | .br | |
209 | blktrace (8), blkparse (1), btreplay (8) | |
210 |