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 ] [-k ] [ -w time ] [
12       -a 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  kill  utility  invocation).
68         There are two ways to modify this:
69
70
71         1. You  may  utilise  the  blktrace  utility itself to kill a running
72            trace -- via the -k option.
73
74
75         2. You can specify a run-time duration for blktrace via the -w option
76            -- then blktrace will run for the specified number of seconds, and
77            then halt.
78
79
80

OPTIONS

82       -A hex-mask
83       --set-mask=hex-mask
84              Set filter mask to hex-mask (see below for masks)
85
86       -a mask
87       --act-mask=mask
88              Add mask to current filter (see below for masks)
89
90       -b size
91       --buffer-size=size
92              Specifies buffer size for event extraction (scaled by 1024). The
93              default buffer size is 512KiB.
94
95       -d dev
96       --dev=dev
97              Adds dev as a device to trace
98
99       -I file
100       --input-devs=file
101              Adds the devices found in file as devices to trace
102
103       -k
104       --kill
105              Kill on-going trace
106
107       -n num-sub
108       --num-sub=num-sub
109              Specifies  number  of buffers to use. blktrace defaults to 4 sub
110              buffers.
111
112       -o file
113       --output=file
114              Prepend file to output file name(s)
115
116       -r rel-path
117       --relay=rel-path
118              Specifies debugfs mount point
119
120       -V
121       --version Outputs version
122
123       -w seconds
124       --stopwatch=seconds
125              Sets run time to the number of seconds specified
126
127
128

FILTER MASKS

130       The following masks may be passed with the -a command line option, mul‐
131       tiple filters may be combined via multiple -a command line options.
132
133              barrier: barrier attribute
134              complete: completed by driver
135              fs: requests
136              issue: issued to driver
137              pc: packet command events
138              queue: queue operations
139              read: read traces
140              requeue: requeue operations
141              sync: synchronous attribute
142              write: write traces
143              notify: trace messages
144
145
146

REQUEST TYPES

148       blktrace  distinguishes between two types of block layer requests, file
149       system and SCSI commands. The former are dubbed fs requests, the latter
150       pc  requests.  File  system  requests are normal read/write operations,
151       i.e.  any type of read or write from a  specific  disk  location  at  a
152       given size. These requests typically originate from a user process, but
153       they may also be initiated by the vm flushing dirty data to disk or the
154       file  system  syncing a super or journal block to disk. pc requests are
155       SCSI commands. blktrace sends the command data block as  a  payload  so
156       that blkparse can decode it.
157
158
159

EXAMPLES

161       To  trace  the i/o on the device /dev/hda and parse the output to human
162       readable form, use the following command:
163
164           % blktrace -d /dev/sda -o - | blkparse -i -
165
166       This same behaviour can be achieve with the convenience script  btrace.
167       The command
168
169           % btrace /dev/sda
170
171       has exactly the same effect as the previous command. See btrace (8) for
172       more information.
173
174       To trace the i/o on a device and save the output for  later  processing
175       with blkparse, use blktrace like this:
176
177           % blktrace /dev/sda /dev/sdb
178
179       This  will  trace i/o on the devices /dev/sda and /dev/sdb and save the
180       recorded information in the files sda and sdb in the current directory,
181       for  the  two  different devices, respectively.  This trace information
182       can later be parsed by the blkparse utility:
183
184           % blkparse sda sdb
185
186       which will output the previously recorded tracing information in  human
187       readable form to stdout.  See blkparse (1) for more information.
188
189
190

AUTHORS

192       blktrace  was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.
193       This man page was  created  from  the  blktrace  documentation  by  Bas
194       Zoetekouw.
195
196
197

REPORTING BUGS

199       Report bugs to <linux-btrace@vger.kernel.org>
200
201
203       Copyright © 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
204       This  is  free  software.   You may redistribute copies of it under the
205       terms      of      the      GNU      General       Public       License
206       <http://www.gnu.org/licenses/gpl.html>.   There  is NO WARRANTY, to the
207       extent permitted by law.
208       This manual page was created for  Debian  by  Bas  Zoetekouw.   It  was
209       derived  from  the  documentation provided by the authors and it may be
210       used, distributed and modified under the terms of the GNU General  Pub‐
211       lic License, version 2.
212       On  Debian  systems,  the text of the GNU General Public License can be
213       found in /usr/share/common-licenses/GPL-2.
214
215

SEE ALSO

217       btrace (8), blkparse (1), verify_blkparse (1),  blkrawverify  (1),  btt
218       (1)
219
220
221
222
223blktrace git-20070306202522     March  6, 2007                     BLKTRACE(8)
Impressum