1BLKTRACE(8)                                                        BLKTRACE(8)
2
3
4

NAME

6       blktrace - generate traces of the i/o traffic on block devices
7
8
9

SYNOPSIS

11       blktrace  -d  dev  [  -r  debugfs_path ] [ -o output ] [ -w time ] [ -a
12       action ] [ -A action_mask ] [ -v ]
13
14
15

DESCRIPTION

17       blktrace is a block layer IO tracing mechanism which provides  detailed
18       information  about request queue operations up to user space. There are
19       three major components: a kernel component, a utility to record the i/o
20       trace  information  for the kernel to user space, and utilities to ana‐
21       lyse and view the trace information.  This man page describes blktrace,
22       which  records  the  i/o  event  trace information for a specific block
23       device to a file.
24
25       The blktrace utility extracts event traces from  the  kernel  (via  the
26       relaying  through  the debug file system). Some background details con‐
27       cerning the run-time behaviour of blktrace will help to understand some
28       of the more arcane command line options:
29
30
31       - blktrace  receives  data from the kernel in buffers passed up through
32         the debug file system (relay). Each device being traced  has  a  file
33         created  in  the mounted directory for the debugfs, which defaults to
34         /sys/kernel/debug -- this can be overridden with the -r command  line
35         argument.
36
37
38       - blktrace  defaults  to  collecting  all events that can be traced. To
39         limit the events being captured, you can specify one or  more  filter
40         masks via the -a option.
41
42         Alternatively,  one may specify the entire mask utilising a hexadeci‐
43         mal value that is version-specific. (Requires  understanding  of  the
44         internal representation of the filter mask.)
45
46
47       - As  noted  above,  the  events  are passed up via a series of buffers
48         stored into debugfs files. The size and  number  of  buffers  can  be
49         specified via the -b and -n arguments respectively.
50
51
52       - blktrace  stores  the  extracted  data into files stored in the local
53         directory. The format of the file names is (by  default)  device.blk‐
54         trace.cpu, where device is the base device name (e.g, if we are trac‐
55         ing /dev/sda, the base device name would be sda); and cpu  identifies
56         a CPU for the event stream.
57
58         The  device  portion of the event file name can be changed via the -o
59         option.
60
61
62       - blktrace may also be run concurrently with blkparse to  produce  live
63         output -- to do this specify -o - for blktrace.
64
65
66       - The default behaviour for blktrace is to run forever until explicitly
67         killed by the user (via a control-C, or sending SIGINT signal to  the
68         process  via invocation the kill (1) utility). Also you can specify a
69         run-time duration for blktrace via the -w  option  --  then  blktrace
70         will run for the specified number of seconds, and then halt.
71
72
73

OPTIONS

75       -A hex-mask
76       --set-mask=hex-mask
77              Set filter mask to hex-mask (see below for masks)
78
79       -a mask
80       --act-mask=mask
81              Add mask to current filter (see below for masks)
82
83       -b size
84       --buffer-size=size
85              Specifies buffer size for event extraction (scaled by 1024). The
86              default buffer size is 512KiB.
87
88       -d dev
89       --dev=dev
90              Adds dev as a device to trace
91
92       -I file
93       --input-devs=file
94              Adds the devices found in file as devices to trace
95
96       -n num-sub
97       --num-sub-buffers=num-sub
98              Specifies number of buffers to use. blktrace defaults to  4  sub
99              buffers.
100
101       -l
102       --listen
103              Run in network listen mode (blktrace server)
104
105       -h hostname
106       --host=hostname
107              Run in network client mode, connecting to the given host
108
109       -p number
110       --port=number
111              Network port to use (default 8462)
112
113       -s
114       --no-sendfile
115              Make the network client NOT use sendfile() to transfer data
116
117       -o basename
118       --output=basename
119              Specifies  base  name  for  input  files. Default is device.blk‐
120              trace.cpu.  Specifying -o - runs  in  live  mode  with  blkparse
121              (writing data to standard out).
122
123       -D dir
124       --output-dir=dir
125              Prepend file to output file name(s)
126
127              This  only  works when supplying a single device, or when piping
128              the output via "-o -" with multiple devices.
129
130       -r rel-path
131       --relay=rel-path
132              Specifies debugfs mount point
133
134       -v
135       --version
136              Outputs version
137
138       -V
139       --version
140              Outputs version
141
142       -w seconds
143       --stopwatch=seconds
144              Sets run time to the number of seconds specified
145
146
147

FILTER MASKS

149       The following masks may be passed with the -a command line option, mul‐
150       tiple filters may be combined via multiple -a command line options.
151
152              barrier: barrier attribute
153              complete: completed by driver
154              discard: discard / trim traces
155              fs: requests
156              issue: issued to driver
157              pc: packet command events
158              queue: queue operations
159              read: read traces
160              requeue: requeue operations
161              sync: synchronous attribute
162              write: write traces
163              notify: trace messages
164              drv_data: additional driver specific trace
165
166
167

REQUEST TYPES

169       blktrace  distinguishes between two types of block layer requests, file
170       system and SCSI commands. The former are dubbed fs requests, the latter
171       pc  requests.  File  system  requests are normal read/write operations,
172       i.e.  any type of read or write from a  specific  disk  location  at  a
173       given size. These requests typically originate from a user process, but
174       they may also be initiated by the vm flushing dirty data to disk or the
175       file  system  syncing a super or journal block to disk. pc requests are
176       SCSI commands. blktrace sends the command data block as  a  payload  so
177       that blkparse can decode it.
178
179
180

EXAMPLES

182       To  trace  the i/o on the device /dev/sda and parse the output to human
183       readable form, use the following command:
184
185           % blktrace -d /dev/sda -o - | blkparse -i -
186
187       This same behaviour can be achieve with the convenience script  btrace.
188       The command
189
190           % btrace /dev/sda
191
192       has exactly the same effect as the previous command. See btrace (8) for
193       more information.
194
195       To trace the i/o on a device and save the output for  later  processing
196       with blkparse, use blktrace like this:
197
198           % blktrace /dev/sda /dev/sdb
199
200       This  will  trace i/o on the devices /dev/sda and /dev/sdb and save the
201       recorded information in the files sda and sdb in the current directory,
202       for  the  two  different devices, respectively.  This trace information
203       can later be parsed by the blkparse utility:
204
205           % blkparse sda sdb
206
207       which will output the previously recorded tracing information in  human
208       readable form to stdout.  See blkparse (1) for more information.
209
210
211

AUTHORS

213       blktrace  was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.
214       This man page was  created  from  the  blktrace  documentation  by  Bas
215       Zoetekouw.
216
217
218

REPORTING BUGS

220       Report bugs to <linux-btrace@vger.kernel.org>
221
222
224       Copyright © 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
225       This  is  free  software.   You may redistribute copies of it under the
226       terms      of      the      GNU      General       Public       License
227       <http://www.gnu.org/licenses/gpl.html>.   There  is NO WARRANTY, to the
228       extent permitted by law.
229       This manual page was created for  Debian  by  Bas  Zoetekouw.   It  was
230       derived  from  the  documentation provided by the authors and it may be
231       used, distributed and modified under the terms of the GNU General  Pub‐
232       lic License, version 2.
233       On  Debian  systems,  the text of the GNU General Public License can be
234       found in /usr/share/common-licenses/GPL-2.
235
236

SEE ALSO

238       btrace (8), blkparse (1), verify_blkparse (1),  blkrawverify  (1),  btt
239       (1)
240
241
242
243
244blktrace git-20070306202522     March  6, 2007                     BLKTRACE(8)
Impressum