Added no messages option to blkparse.c
[blktrace.git] / doc / blktrace.8
CommitLineData
98eee4e4
JA
1.TH BLKTRACE 8 "March 6, 2007" "blktrace git\-20070306202522" ""
2
3
4.SH NAME
5blktrace \- 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
14blktrace is a block layer IO tracing mechanism which provides detailed
15information about request queue operations up to user space. There are three
16major components: a kernel component, a utility to record the i/o trace
17information for the kernel to user space, and utilities to analyse and view the
18trace information. This man page describes blktrace, which records the i/o event
19trace information for a specific block device to a file.
20
21The \fBblktrace\fR utility extracts event traces from the kernel (via
22the relaying through the debug file system). Some background details
23concerning the run\-time behaviour of blktrace will help to understand some
24of the more arcane command line options:
25
26.TP 2
27\-
28blktrace receives data from the kernel in buffers passed up through the
29debug file system (relay). Each device being traced has a file created in
30the mounted directory for the debugfs, which defaults to
31\fI/sys/kernel/debug\fR \-\- this can be overridden with the \fB\-r\fR command
32line argument.
33
34.TP 2
35\-
36blktrace defaults to collecting all events that can be traced. To
37limit the events being captured, you can specify one or more filter masks
38via the \fB\-a\fR option.
39
40Alternatively, one may specify the entire mask utilising a hexadecimal
41value that is version\-specific. (Requires understanding of the internal
42representation of the filter mask.)
43
44.TP 2
45\-
46As noted above, the events are passed up via a series of buffers stored
47into debugfs files. The size and number of buffers can be specified via
48the \fB\-b\fR and \fB\-n\fR arguments respectively.
49
50.TP 2
51\-
52blktrace stores the extracted data into files stored in the
53local directory. The format of the file names is (by default)
54\fBdevice\fR.\fBblktrace\fR.\fBcpu\fR, where \fBdevice\fR is the base
55device name (e.g, if we are tracing /dev/sda, the base device name would
56be \fBsda\fR); and \fBcpu\fR identifies a CPU for the event stream.
57
58The \fBdevice\fR portion of the event file name can be changed via
59the \fB\-o\fR option.
60
61.TP 2
62\-
63blktrace 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\-
68The default behaviour for blktrace is to run forever until explicitly
69killed by the user (via a control-C, or kill utility invocation).
70There are two ways to modify this:
71
72.TP 5
73 1.
74You may utilise the blktrace utility itself to kill
75a running trace -- via the \fB\-k\fR option.
76
77.TP 5
78 2.
79You can specify a run-time duration for blktrace via the
80\fB\-w\fR option -- then blktrace will run for the specified number
81of 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
90Set 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
97Add \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
104Specifies buffer size for event extraction (scaled by 1024). The default
105buffer size is 512KiB.
98eee4e4
JA
106.RE
107
108\-d \fIdev\fR
109.br
110\-\-dev=\fIdev\fR
111.RS
112Adds \fIdev\fR as a device to trace
113.RE
114
115\-I \fIfile\fR
116.br
117\-\-input-devs=\fIfile\fR
118.RS
119Adds the devices found in \fIfile\fR as devices to trace
bb4afebb 120.RE
98eee4e4
JA
121
122\-k
123.br
124\-\-kill
125.RS
126Kill on-going trace
127.RE
128
129\-n \fInum\-sub\fR
130.br
131\-\-num\-sub=\fInum-sub\fR
132.RS
0bf92681 133Specifies 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
140Prepend \fIfile\fR to output file name(s)
141.RE
142
143\-r \fIrel-path\fR
144.br
145\-\-relay=\fIrel-path\fR
146.RS
147Specifies debugfs mount point
148.RE
149
150\-V
151.br
152\-\-version
153Outputs version
154.RE
155
156\-w \fIseconds\fR
157.br
158\-\-stopwatch=\fIseconds\fR
159.RS
160Sets run time to the number of seconds specified
161.RE
162
163
164.SH FILTER MASKS
165The following masks may be passed with the \fI\-a\fR command line
166option, multiple filters may be combined via multiple \fI\-a\fR command
167line 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.RE
190
191
192.SH REQUEST TYPES
193blktrace distinguishes between two types of block layer requests, file system
194and SCSI commands. The former are dubbed \fBfs\fR requests, the latter
195\fBpc\fR requests. File system requests are normal read/write operations, i.e.
196any type of read or write from a specific disk location at a given size. These
197requests typically originate from a user process, but they may also be
198initiated by the vm flushing dirty data to disk or the file system syncing a
199super or journal block to disk. \fBpc\fR requests are SCSI commands. blktrace
200sends the command data block as a payload so that blkparse can decode it.
201
202
203.SH EXAMPLES
6f2cb32b 204To trace the i/o on the device \fI/dev/hda\fR and parse the output to human
98eee4e4
JA
205readable form, use the following command:
206
207 % blktrace \-d /dev/sda \-o \- | blkparse \-i \-
208
209This same behaviour can be achieve with the convenience script \fIbtrace\fR.
210The command
211
212 % btrace /dev/sda
213
214has exactly the same effect as the previous command. See \fIbtrace\fR (8) for
215more information.
216
217To trace the i/o on a device and save the output for later processing with
218\fIblkparse\fR, use \fIblktrace\fR like this:
219
220 % blktrace /dev/sda /dev/sdb
221
222This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save
223the recorded information in the files \fIsda\fR and \fIsdb\fR in the current
224directory, for the two different devices, respectively. This trace
225information can later be parsed by the \fIblkparse\fR utility:
226
227 % blkparse sda sdb
228
229which will output the previously recorded tracing information in human
230readable form to stdout. See \fIblkparse\fR (1) for more information.
231
232
233.SH AUTHORS
234blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This
235man page was created from the blktrace documentation by Bas Zoetekouw.
236
237
238.SH "REPORTING BUGS"
239Report bugs to <linux\-btrace@vger.kernel.org>
240
241.SH COPYRIGHT
242Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
243.br
244This is free software. You may redistribute copies of it under the terms of
245the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
246There is NO WARRANTY, to the extent permitted by law.
247.br
248This manual page was created for Debian by Bas Zoetekouw. It was derived from
249the documentation provided by the authors and it may be used, distributed and
250modified under the terms of the GNU General Public License, version 2.
251.br
252On Debian systems, the text of the GNU General Public License can be found in
253/usr/share/common\-licenses/GPL\-2.
254
255.SH "SEE ALSO"
256btrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)
257