4 Written by Jens Axboe <axboe@kernel.dk> (initial version and kernel support),
5 Alan D. Brunelle (threading and splitup into two seperate programs),
6 Nathan Scott <nathans@sgi.com> (bug fixes, process names, multiple devices)
7 Also thanks to Tom Zanussi <zanussi@us.ibm.com> for good input and
14 blktrace was integrated into the mainline kernel between 2.6.16 and 2.6.17-rc1.
15 The target trace needs to run on a kernel at least that new. The blktrace
16 repository contains a kernel patch against 2.6.16 and will continue to do
17 so until 2.6.17 is released. If you forgot where you got it, the url is:
19 rsync://rsync.kernel.org/pub/scm/linux/kernel/git/axboe/blktrace.git
21 If you don't have git, you can get hourly snapshots from:
23 http://www.kernel.org/pub/linux/kernel/people/axboe/blktrace/
25 The snapshots include the full git object database as well. kernel.org has
26 excessively long mirror times, so if you have git installed, you can pull
29 git://brick.kernel.dk/data/git/blktrace.git
31 For browsing the repo over http and viewing history etc, you can direct
40 $ blktrace -d <dev> [ -r debug_path ] [ -o output ] [ -k ] [ -w time ]
41 [ -a action ] [ -A action mask ]
43 -d Use specified device. May also be given last after options.
44 -r Path to mounted debugfs, defaults to /debug.
45 -o File(s) to send output to.
46 -D Directory to prepend to output file names.
47 -k Kill running trace.
48 -w Stop after defined time, in seconds.
49 -a Only trace specific actions (use more -a options to add actions).
50 Available actions are:
63 -A Give the trace mask directly as a number.
65 -b Sub buffer size in KiB.
66 -n Number of sub buffers.
67 -l Run in network listen mode (blktrace server)
68 -h Run in network client mode, connecting to the given host
69 -p Network port to use (default 8462)
70 -s Disable network client use of sendfile() to transfer data
71 -V Print program version info.
73 $ blkparse -i <input> [ -o <output> ] [ -b rb_batch ] [ -s ] [ -t ] [ -q ]
74 [ -w start:stop ] [ -f output format ] [ -F format spec ]
77 -i Input file containing trace data, or '-' for stdin.
78 -D Directory to prepend to input file names.
79 -o Output file. If not given, output is stdout.
80 -b stdin read batching.
81 -s Show per-program io statistics.
82 -h Hash processes by name, not pid.
83 -t Track individual ios. Will tell you the time a request took to
84 get queued, to get dispatched, and to get completed.
85 -q Quiet. Don't display any stats at the end of the trace.
86 -w Only parse data between the given time interval in seconds. If
87 'start' isn't given, blkparse defaults the start time to 0.
88 -d Dump sorted data in binary format
89 -f Output format. Customize the output format. The format field
94 %C - Task command name
101 %n - Number of sectors
106 %t - Time (wallclock - nanoseconds)
107 %T - Time (wallclock - seconds)
108 %u - Time (processing - microseconds)
111 -F Format specification. The individual specifiers are:
120 M - Both front and back merge
130 -v More verbose for marginal errors.
131 -V Print program version info.
133 $ verify_blkparse filename
135 Verifies an output file from blkparse. All it does is check if
136 the events in the file are correctly time ordered. If an entry
137 is found that isn't ordered, it's dumped to stdout.
139 $ blkrawverify <dev> [<dev>...]
141 The blkrawverify utility can be used to verify data retrieved
142 via blktrace. It will check for valid event formats, forward
143 progressing sequence numbers and time stamps, also does reasonable
144 checks for other potential issues within invidividual events.
146 Errors found will be tracked in <dev>.verify.out.
148 If you want to do live tracing, you can pipe the data between blktrace
151 % blktrace -d <device> -o - | blkparse -i -
153 This has a small risk of displaying some traces a little out of sync, since
154 it will do batch sorts of input events. Similarly, you can do traces over
155 the network. The network 'server' must run:
159 to listen to incoming blktrace connections, while the client should use
161 % blktrace -d /dev/sda -h <server hostname>
163 to connect and transfer data over the network.
169 A users guide is distributed with the source. It is in latex, a
170 'make docs' will build a PDF in doc/. You need tetex and latex installed
171 to build the document.
177 vger hosts a mailing list dedicated to btrace discussion and development.
178 The list is called linux-btrace@vger.kernel.org, subscribe by sending
179 a mail to majordomo@vger.kernel.org with 'subscribe linux-btrace' in
184 2006-09-05, Jens Axboe <axboe@kernel.dk>