Commit | Line | Data |
---|---|---|
98eee4e4 JA |
1 | .TH BLKTRACE 8 "March 6, 2007" "blktrace git\-20070306202522" "" |
2 | ||
3 | ||
4 | .SH NAME | |
5 | blktrace \- generate traces of the i/o traffic on block devices | |
6 | ||
7 | ||
8 | .SH SYNOPSIS | |
9 | .B blktrace \-d \fIdev\fR [ \-r \fIdebugfs_path\fR ] [ \-o \fIoutput\fR ] [\-k ] [ \-w \fItime\fR ] [ \-a \fIaction\fR ] [ \-A \fIaction_mask\fR ] [ \-v ] | |
10 | .br | |
11 | ||
12 | ||
13 | .SH DESCRIPTION | |
14 | blktrace is a block layer IO tracing mechanism which provides detailed | |
15 | information about request queue operations up to user space. There are three | |
16 | major components: a kernel component, a utility to record the i/o trace | |
17 | information for the kernel to user space, and utilities to analyse and view the | |
18 | trace information. This man page describes blktrace, which records the i/o event | |
19 | trace information for a specific block device to a file. | |
20 | ||
21 | The \fBblktrace\fR utility extracts event traces from the kernel (via | |
22 | the relaying through the debug file system). Some background details | |
23 | concerning the run\-time behaviour of blktrace will help to understand some | |
24 | of the more arcane command line options: | |
25 | ||
26 | .TP 2 | |
27 | \- | |
28 | blktrace receives data from the kernel in buffers passed up through the | |
29 | debug file system (relay). Each device being traced has a file created in | |
30 | the mounted directory for the debugfs, which defaults to | |
31 | \fI/sys/kernel/debug\fR \-\- this can be overridden with the \fB\-r\fR command | |
32 | line argument. | |
33 | ||
34 | .TP 2 | |
35 | \- | |
36 | blktrace defaults to collecting all events that can be traced. To | |
37 | limit the events being captured, you can specify one or more filter masks | |
38 | via the \fB\-a\fR option. | |
39 | ||
40 | Alternatively, one may specify the entire mask utilising a hexadecimal | |
41 | value that is version\-specific. (Requires understanding of the internal | |
42 | representation of the filter mask.) | |
43 | ||
44 | .TP 2 | |
45 | \- | |
46 | As noted above, the events are passed up via a series of buffers stored | |
47 | into debugfs files. The size and number of buffers can be specified via | |
48 | the \fB\-b\fR and \fB\-n\fR arguments respectively. | |
49 | ||
50 | .TP 2 | |
51 | \- | |
52 | blktrace stores the extracted data into files stored in the | |
53 | local directory. The format of the file names is (by default) | |
54 | \fBdevice\fR.\fBblktrace\fR.\fBcpu\fR, where \fBdevice\fR is the base | |
55 | device name (e.g, if we are tracing /dev/sda, the base device name would | |
56 | be \fBsda\fR); and \fBcpu\fR identifies a CPU for the event stream. | |
57 | ||
58 | The \fBdevice\fR portion of the event file name can be changed via | |
59 | the \fB\-o\fR option. | |
60 | ||
61 | .TP 2 | |
62 | \- | |
63 | blktrace may also be run concurrently with blkparse to produce | |
64 | \fBlive\fR output \-\- to do this specify \fB\-o \-\fR for blktrace. | |
65 | ||
66 | .TP 2 | |
67 | \- | |
68 | The default behaviour for blktrace is to run forever until explicitly | |
fb7f8667 ES |
69 | killed by the user (via a control-C, or sending SIGINT signal to the |
70 | process via invocation the kill (1) utility). Also you can specify a | |
71 | run-time duration for blktrace via the \fB\-w\fR option -- then | |
72 | blktrace will run for the specified number of seconds, and then halt. | |
98eee4e4 JA |
73 | |
74 | ||
75 | .SH OPTIONS | |
76 | ||
77 | \-A \fIhex-mask\fR | |
78 | .br | |
79 | \-\-set-mask=\fIhex-mask\fR | |
80 | .RS | |
81 | Set filter mask to \fIhex-mask\fR (see below for masks) | |
82 | .RE | |
83 | ||
84 | \-a \fImask\fR | |
85 | .br | |
86 | \-\-act-mask=\fImask\fR | |
87 | .RS | |
88 | Add \fImask\fR to current filter (see below for masks) | |
89 | .RE | |
90 | ||
91 | \-b \fIsize\fR | |
92 | .br | |
93 | \-\-buffer\-size=\fIsize\fR | |
94 | .RS | |
0bf92681 JA |
95 | Specifies buffer size for event extraction (scaled by 1024). The default |
96 | buffer size is 512KiB. | |
98eee4e4 JA |
97 | .RE |
98 | ||
99 | \-d \fIdev\fR | |
100 | .br | |
101 | \-\-dev=\fIdev\fR | |
102 | .RS | |
103 | Adds \fIdev\fR as a device to trace | |
104 | .RE | |
105 | ||
106 | \-I \fIfile\fR | |
107 | .br | |
b9a7e9fc | 108 | \-\-input\-devs=\fIfile\fR |
98eee4e4 JA |
109 | .RS |
110 | Adds the devices found in \fIfile\fR as devices to trace | |
bb4afebb | 111 | .RE |
98eee4e4 | 112 | |
98eee4e4 JA |
113 | \-n \fInum\-sub\fR |
114 | .br | |
b9a7e9fc | 115 | \-\-num\-sub\-buffers=\fInum-sub\fR |
98eee4e4 | 116 | .RS |
0bf92681 | 117 | Specifies number of buffers to use. blktrace defaults to 4 sub buffers. |
98eee4e4 JA |
118 | .RE |
119 | ||
b9a7e9fc | 120 | \-l |
98eee4e4 | 121 | .br |
b9a7e9fc | 122 | \-\-listen |
98eee4e4 | 123 | .RS |
b9a7e9fc ES |
124 | Run in network listen mode (blktrace server) |
125 | .RE | |
126 | ||
127 | \-h \fIhostname\fR | |
128 | .br | |
129 | \-\-host=\fIhostname\fR | |
130 | .RS | |
131 | Run in network client mode, connecting to the given host | |
132 | .RE | |
133 | ||
134 | \-p \fInumber\fR | |
135 | .br | |
136 | \-\-port=\fInumber\fR | |
137 | .RS | |
138 | Network port to use (default 8462) | |
139 | .RE | |
140 | ||
141 | \-s | |
142 | .br | |
143 | \-\-no\-sendfile | |
144 | .RS | |
145 | Make the network client NOT use sendfile() to transfer data | |
146 | .RE | |
147 | ||
148 | \-o \fIbasename\fR | |
149 | .br | |
150 | \-\-output=\fIbasename\fR | |
151 | .RS | |
152 | Specifies base name for input files. Default is device.blktrace.cpu. | |
153 | Specifying -o - runs in live mode with blkparse (writing data to standard out). | |
154 | .RE | |
155 | ||
156 | \-D \fIdir\fR | |
157 | .br | |
158 | \-\-output\-dir=\fIdir\fR | |
159 | .RS | |
160 | Prepend \fIfile\fR to output file name(s) | |
ce2151eb AB |
161 | |
162 | This only works when supplying a single device, or when piping the output | |
163 | via "-o -" with multiple devices. | |
98eee4e4 JA |
164 | .RE |
165 | ||
166 | \-r \fIrel-path\fR | |
167 | .br | |
168 | \-\-relay=\fIrel-path\fR | |
169 | .RS | |
170 | Specifies debugfs mount point | |
171 | .RE | |
172 | ||
b9a7e9fc ES |
173 | \-v |
174 | .br | |
175 | \-\-version | |
176 | .RS | |
177 | Outputs version | |
178 | .RE | |
179 | ||
98eee4e4 JA |
180 | \-V |
181 | .br | |
b9a7e9fc ES |
182 | \-\-version |
183 | .RS | |
98eee4e4 JA |
184 | Outputs version |
185 | .RE | |
186 | ||
187 | \-w \fIseconds\fR | |
188 | .br | |
189 | \-\-stopwatch=\fIseconds\fR | |
190 | .RS | |
191 | Sets run time to the number of seconds specified | |
192 | .RE | |
193 | ||
194 | ||
195 | .SH FILTER MASKS | |
196 | The following masks may be passed with the \fI\-a\fR command line | |
197 | option, multiple filters may be combined via multiple \fI\-a\fR command | |
198 | line options. | |
199 | ||
200 | .RS | |
201 | \fIbarrier\fR: barrier attribute | |
202 | .br | |
d8ba9b68 | 203 | \fIcomplete\fR: completed by driver |
98eee4e4 JA |
204 | .br |
205 | \fIfs\fR: requests | |
206 | .br | |
207 | \fIissue\fR: issued to driver | |
208 | .br | |
209 | \fIpc\fR: packet command events | |
210 | .br | |
211 | \fIqueue\fR: queue operations | |
212 | .br | |
213 | \fIread\fR: read traces | |
214 | .br | |
215 | \fIrequeue\fR: requeue operations | |
216 | .br | |
217 | \fIsync\fR: synchronous attribute | |
218 | .br | |
219 | \fIwrite\fR: write traces | |
cfa089d4 CHL |
220 | .br |
221 | \fInotify\fR: trace messages | |
cab38cd2 ES |
222 | .br |
223 | \fIdrv_data\fR: additional driver specific trace | |
98eee4e4 JA |
224 | .RE |
225 | ||
226 | ||
227 | .SH REQUEST TYPES | |
228 | blktrace distinguishes between two types of block layer requests, file system | |
229 | and SCSI commands. The former are dubbed \fBfs\fR requests, the latter | |
230 | \fBpc\fR requests. File system requests are normal read/write operations, i.e. | |
231 | any type of read or write from a specific disk location at a given size. These | |
232 | requests typically originate from a user process, but they may also be | |
233 | initiated by the vm flushing dirty data to disk or the file system syncing a | |
234 | super or journal block to disk. \fBpc\fR requests are SCSI commands. blktrace | |
235 | sends the command data block as a payload so that blkparse can decode it. | |
236 | ||
237 | ||
238 | .SH EXAMPLES | |
6f2cb32b | 239 | To trace the i/o on the device \fI/dev/hda\fR and parse the output to human |
98eee4e4 JA |
240 | readable form, use the following command: |
241 | ||
242 | % blktrace \-d /dev/sda \-o \- | blkparse \-i \- | |
243 | ||
244 | This same behaviour can be achieve with the convenience script \fIbtrace\fR. | |
245 | The command | |
246 | ||
247 | % btrace /dev/sda | |
248 | ||
249 | has exactly the same effect as the previous command. See \fIbtrace\fR (8) for | |
250 | more information. | |
251 | ||
252 | To trace the i/o on a device and save the output for later processing with | |
253 | \fIblkparse\fR, use \fIblktrace\fR like this: | |
254 | ||
255 | % blktrace /dev/sda /dev/sdb | |
256 | ||
257 | This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save | |
258 | the recorded information in the files \fIsda\fR and \fIsdb\fR in the current | |
259 | directory, for the two different devices, respectively. This trace | |
260 | information can later be parsed by the \fIblkparse\fR utility: | |
261 | ||
262 | % blkparse sda sdb | |
263 | ||
264 | which will output the previously recorded tracing information in human | |
265 | readable form to stdout. See \fIblkparse\fR (1) for more information. | |
266 | ||
267 | ||
268 | .SH AUTHORS | |
269 | blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This | |
270 | man page was created from the blktrace documentation by Bas Zoetekouw. | |
271 | ||
272 | ||
273 | .SH "REPORTING BUGS" | |
274 | Report bugs to <linux\-btrace@vger.kernel.org> | |
275 | ||
276 | .SH COPYRIGHT | |
277 | Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. | |
278 | .br | |
279 | This is free software. You may redistribute copies of it under the terms of | |
280 | the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. | |
281 | There is NO WARRANTY, to the extent permitted by law. | |
282 | .br | |
283 | This manual page was created for Debian by Bas Zoetekouw. It was derived from | |
284 | the documentation provided by the authors and it may be used, distributed and | |
285 | modified under the terms of the GNU General Public License, version 2. | |
286 | .br | |
287 | On Debian systems, the text of the GNU General Public License can be found in | |
288 | /usr/share/common\-licenses/GPL\-2. | |
289 | ||
290 | .SH "SEE ALSO" | |
291 | btrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1) | |
292 |