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 | |
69 | killed by the user (via a control-C, or kill utility invocation). | |
70 | There are two ways to modify this: | |
71 | ||
72 | .TP 5 | |
73 | 1. | |
74 | You may utilise the blktrace utility itself to kill | |
75 | a running trace -- via the \fB\-k\fR option. | |
76 | ||
77 | .TP 5 | |
78 | 2. | |
79 | You can specify a run-time duration for blktrace via the | |
80 | \fB\-w\fR option -- then blktrace will run for the specified number | |
81 | of seconds, and then halt. | |
82 | ||
83 | ||
84 | .SH OPTIONS | |
85 | ||
86 | \-A \fIhex-mask\fR | |
87 | .br | |
88 | \-\-set-mask=\fIhex-mask\fR | |
89 | .RS | |
90 | Set filter mask to \fIhex-mask\fR (see below for masks) | |
91 | .RE | |
92 | ||
93 | \-a \fImask\fR | |
94 | .br | |
95 | \-\-act-mask=\fImask\fR | |
96 | .RS | |
97 | Add \fImask\fR to current filter (see below for masks) | |
98 | .RE | |
99 | ||
100 | \-b \fIsize\fR | |
101 | .br | |
102 | \-\-buffer\-size=\fIsize\fR | |
103 | .RS | |
0bf92681 JA |
104 | Specifies buffer size for event extraction (scaled by 1024). The default |
105 | buffer size is 512KiB. | |
98eee4e4 JA |
106 | .RE |
107 | ||
108 | \-d \fIdev\fR | |
109 | .br | |
110 | \-\-dev=\fIdev\fR | |
111 | .RS | |
112 | Adds \fIdev\fR as a device to trace | |
113 | .RE | |
114 | ||
115 | \-I \fIfile\fR | |
116 | .br | |
117 | \-\-input-devs=\fIfile\fR | |
118 | .RS | |
119 | Adds the devices found in \fIfile\fR as devices to trace | |
bb4afebb | 120 | .RE |
98eee4e4 JA |
121 | |
122 | \-k | |
123 | .br | |
124 | \-\-kill | |
125 | .RS | |
126 | Kill on-going trace | |
127 | .RE | |
128 | ||
129 | \-n \fInum\-sub\fR | |
130 | .br | |
131 | \-\-num\-sub=\fInum-sub\fR | |
132 | .RS | |
0bf92681 | 133 | Specifies number of buffers to use. blktrace defaults to 4 sub buffers. |
98eee4e4 JA |
134 | .RE |
135 | ||
136 | \-o \fIfile\fR | |
137 | .br | |
138 | \-\-output=\fIfile\fR | |
139 | .RS | |
140 | Prepend \fIfile\fR to output file name(s) | |
141 | .RE | |
142 | ||
143 | \-r \fIrel-path\fR | |
144 | .br | |
145 | \-\-relay=\fIrel-path\fR | |
146 | .RS | |
147 | Specifies debugfs mount point | |
148 | .RE | |
149 | ||
150 | \-V | |
151 | .br | |
152 | \-\-version | |
153 | Outputs version | |
154 | .RE | |
155 | ||
156 | \-w \fIseconds\fR | |
157 | .br | |
158 | \-\-stopwatch=\fIseconds\fR | |
159 | .RS | |
160 | Sets run time to the number of seconds specified | |
161 | .RE | |
162 | ||
163 | ||
164 | .SH FILTER MASKS | |
165 | The following masks may be passed with the \fI\-a\fR command line | |
166 | option, multiple filters may be combined via multiple \fI\-a\fR command | |
167 | line options. | |
168 | ||
169 | .RS | |
170 | \fIbarrier\fR: barrier attribute | |
171 | .br | |
172 | \fIcomplete\fR: completed} by driver | |
173 | .br | |
174 | \fIfs\fR: requests | |
175 | .br | |
176 | \fIissue\fR: issued to driver | |
177 | .br | |
178 | \fIpc\fR: packet command events | |
179 | .br | |
180 | \fIqueue\fR: queue operations | |
181 | .br | |
182 | \fIread\fR: read traces | |
183 | .br | |
184 | \fIrequeue\fR: requeue operations | |
185 | .br | |
186 | \fIsync\fR: synchronous attribute | |
187 | .br | |
188 | \fIwrite\fR: write traces | |
cfa089d4 CHL |
189 | .br |
190 | \fInotify\fR: trace messages | |
98eee4e4 JA |
191 | .RE |
192 | ||
193 | ||
194 | .SH REQUEST TYPES | |
195 | blktrace distinguishes between two types of block layer requests, file system | |
196 | and SCSI commands. The former are dubbed \fBfs\fR requests, the latter | |
197 | \fBpc\fR requests. File system requests are normal read/write operations, i.e. | |
198 | any type of read or write from a specific disk location at a given size. These | |
199 | requests typically originate from a user process, but they may also be | |
200 | initiated by the vm flushing dirty data to disk or the file system syncing a | |
201 | super or journal block to disk. \fBpc\fR requests are SCSI commands. blktrace | |
202 | sends the command data block as a payload so that blkparse can decode it. | |
203 | ||
204 | ||
205 | .SH EXAMPLES | |
6f2cb32b | 206 | To trace the i/o on the device \fI/dev/hda\fR and parse the output to human |
98eee4e4 JA |
207 | readable form, use the following command: |
208 | ||
209 | % blktrace \-d /dev/sda \-o \- | blkparse \-i \- | |
210 | ||
211 | This same behaviour can be achieve with the convenience script \fIbtrace\fR. | |
212 | The command | |
213 | ||
214 | % btrace /dev/sda | |
215 | ||
216 | has exactly the same effect as the previous command. See \fIbtrace\fR (8) for | |
217 | more information. | |
218 | ||
219 | To trace the i/o on a device and save the output for later processing with | |
220 | \fIblkparse\fR, use \fIblktrace\fR like this: | |
221 | ||
222 | % blktrace /dev/sda /dev/sdb | |
223 | ||
224 | This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save | |
225 | the recorded information in the files \fIsda\fR and \fIsdb\fR in the current | |
226 | directory, for the two different devices, respectively. This trace | |
227 | information can later be parsed by the \fIblkparse\fR utility: | |
228 | ||
229 | % blkparse sda sdb | |
230 | ||
231 | which will output the previously recorded tracing information in human | |
232 | readable form to stdout. See \fIblkparse\fR (1) for more information. | |
233 | ||
234 | ||
235 | .SH AUTHORS | |
236 | blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This | |
237 | man page was created from the blktrace documentation by Bas Zoetekouw. | |
238 | ||
239 | ||
240 | .SH "REPORTING BUGS" | |
241 | Report bugs to <linux\-btrace@vger.kernel.org> | |
242 | ||
243 | .SH COPYRIGHT | |
244 | Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. | |
245 | .br | |
246 | This is free software. You may redistribute copies of it under the terms of | |
247 | the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. | |
248 | There is NO WARRANTY, to the extent permitted by law. | |
249 | .br | |
250 | This manual page was created for Debian by Bas Zoetekouw. It was derived from | |
251 | the documentation provided by the authors and it may be used, distributed and | |
252 | modified under the terms of the GNU General Public License, version 2. | |
253 | .br | |
254 | On Debian systems, the text of the GNU General Public License can be found in | |
255 | /usr/share/common\-licenses/GPL\-2. | |
256 | ||
257 | .SH "SEE ALSO" | |
258 | btrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1) | |
259 |