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 | |
108 | \-\-input-devs=\fIfile\fR | |
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 | |
115 | \-\-num\-sub=\fInum-sub\fR | |
116 | .RS | |
0bf92681 | 117 | Specifies number of buffers to use. blktrace defaults to 4 sub buffers. |
98eee4e4 JA |
118 | .RE |
119 | ||
120 | \-o \fIfile\fR | |
121 | .br | |
122 | \-\-output=\fIfile\fR | |
123 | .RS | |
124 | Prepend \fIfile\fR to output file name(s) | |
ce2151eb AB |
125 | |
126 | This only works when supplying a single device, or when piping the output | |
127 | via "-o -" with multiple devices. | |
98eee4e4 JA |
128 | .RE |
129 | ||
130 | \-r \fIrel-path\fR | |
131 | .br | |
132 | \-\-relay=\fIrel-path\fR | |
133 | .RS | |
134 | Specifies debugfs mount point | |
135 | .RE | |
136 | ||
137 | \-V | |
138 | .br | |
139 | \-\-version | |
140 | Outputs version | |
141 | .RE | |
142 | ||
143 | \-w \fIseconds\fR | |
144 | .br | |
145 | \-\-stopwatch=\fIseconds\fR | |
146 | .RS | |
147 | Sets run time to the number of seconds specified | |
148 | .RE | |
149 | ||
150 | ||
151 | .SH FILTER MASKS | |
152 | The following masks may be passed with the \fI\-a\fR command line | |
153 | option, multiple filters may be combined via multiple \fI\-a\fR command | |
154 | line options. | |
155 | ||
156 | .RS | |
157 | \fIbarrier\fR: barrier attribute | |
158 | .br | |
d8ba9b68 | 159 | \fIcomplete\fR: completed by driver |
98eee4e4 JA |
160 | .br |
161 | \fIfs\fR: requests | |
162 | .br | |
163 | \fIissue\fR: issued to driver | |
164 | .br | |
165 | \fIpc\fR: packet command events | |
166 | .br | |
167 | \fIqueue\fR: queue operations | |
168 | .br | |
169 | \fIread\fR: read traces | |
170 | .br | |
171 | \fIrequeue\fR: requeue operations | |
172 | .br | |
173 | \fIsync\fR: synchronous attribute | |
174 | .br | |
175 | \fIwrite\fR: write traces | |
cfa089d4 CHL |
176 | .br |
177 | \fInotify\fR: trace messages | |
cab38cd2 ES |
178 | .br |
179 | \fIdrv_data\fR: additional driver specific trace | |
98eee4e4 JA |
180 | .RE |
181 | ||
182 | ||
183 | .SH REQUEST TYPES | |
184 | blktrace distinguishes between two types of block layer requests, file system | |
185 | and SCSI commands. The former are dubbed \fBfs\fR requests, the latter | |
186 | \fBpc\fR requests. File system requests are normal read/write operations, i.e. | |
187 | any type of read or write from a specific disk location at a given size. These | |
188 | requests typically originate from a user process, but they may also be | |
189 | initiated by the vm flushing dirty data to disk or the file system syncing a | |
190 | super or journal block to disk. \fBpc\fR requests are SCSI commands. blktrace | |
191 | sends the command data block as a payload so that blkparse can decode it. | |
192 | ||
193 | ||
194 | .SH EXAMPLES | |
6f2cb32b | 195 | To trace the i/o on the device \fI/dev/hda\fR and parse the output to human |
98eee4e4 JA |
196 | readable form, use the following command: |
197 | ||
198 | % blktrace \-d /dev/sda \-o \- | blkparse \-i \- | |
199 | ||
200 | This same behaviour can be achieve with the convenience script \fIbtrace\fR. | |
201 | The command | |
202 | ||
203 | % btrace /dev/sda | |
204 | ||
205 | has exactly the same effect as the previous command. See \fIbtrace\fR (8) for | |
206 | more information. | |
207 | ||
208 | To trace the i/o on a device and save the output for later processing with | |
209 | \fIblkparse\fR, use \fIblktrace\fR like this: | |
210 | ||
211 | % blktrace /dev/sda /dev/sdb | |
212 | ||
213 | This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save | |
214 | the recorded information in the files \fIsda\fR and \fIsdb\fR in the current | |
215 | directory, for the two different devices, respectively. This trace | |
216 | information can later be parsed by the \fIblkparse\fR utility: | |
217 | ||
218 | % blkparse sda sdb | |
219 | ||
220 | which will output the previously recorded tracing information in human | |
221 | readable form to stdout. See \fIblkparse\fR (1) for more information. | |
222 | ||
223 | ||
224 | .SH AUTHORS | |
225 | blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This | |
226 | man page was created from the blktrace documentation by Bas Zoetekouw. | |
227 | ||
228 | ||
229 | .SH "REPORTING BUGS" | |
230 | Report bugs to <linux\-btrace@vger.kernel.org> | |
231 | ||
232 | .SH COPYRIGHT | |
233 | Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. | |
234 | .br | |
235 | This is free software. You may redistribute copies of it under the terms of | |
236 | the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. | |
237 | There is NO WARRANTY, to the extent permitted by law. | |
238 | .br | |
239 | This manual page was created for Debian by Bas Zoetekouw. It was derived from | |
240 | the documentation provided by the authors and it may be used, distributed and | |
241 | modified under the terms of the GNU General Public License, version 2. | |
242 | .br | |
243 | On Debian systems, the text of the GNU General Public License can be found in | |
244 | /usr/share/common\-licenses/GPL\-2. | |
245 | ||
246 | .SH "SEE ALSO" | |
247 | btrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1) | |
248 |