btt: Added in I/O activity per device and system-wide
[blktrace.git] / doc / blktrace.8
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
104 Specifies buffer size for event extraction (scaled by 1024). The default
105 buffer size is 512KiB.
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
120 .RE
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
133 Specifies number of buffers to use. blktrace defaults to 4 sub buffers.
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
189 .br
190 \fInotify\fR: trace messages
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
206 To trace the i/o on the device \fI/dev/hda\fR and parse the output to human
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