Block IO Tracing
----------------
-Written by Jens Axboe <axboe@suse.de> (initial version and kernel support),
+Written by Jens Axboe <axboe@kernel.dk> (initial version and kernel support),
Alan D. Brunelle (threading and splitup into two seperate programs),
Nathan Scott <nathans@sgi.com> (bug fixes, process names, multiple devices)
+Also thanks to Tom Zanussi <zanussi@us.ibm.com> for good input and
+patches.
Requirements
------------
-You need to be running a 2.6.14-rc2 kernel or newer, with the blk-trace patch
-included in this repository. If you forgot where you got it, the url is:
+blktrace was integrated into the mainline kernel between 2.6.16 and 2.6.17-rc1.
+The target trace needs to run on a kernel at least that new.
-rsync://rsync.kernel.org/pub/scm/linux/kernel/git/axboe/blktrace.git
+git://git.kernel.dk/blktrace.git
If you don't have git, you can get hourly snapshots from:
-http://www.kernel.org/pub/linux/kernel/people/axboe/blktrace/
+http://brick.kernel.dk/snaps/
The snapshots include the full git object database as well. kernel.org has
excessively long mirror times, so if you have git installed, you can pull
the master tree from:
-git://brick.kernel.dk/data/git/blktrace.git
+git://git.kernel.dk/blktrace.git
For browsing the repo over http and viewing history etc, you can direct
your browser to:
-http://brick.kernel.dk/git
+http://git.kernel.dk/
+A blktrace visualization tool, iowatcher, was added to blktrace in version
+1.1.0. It requires librsvg and either png2theora or ffmpeg to generate movies.
Usage
-----
-$ blktrace -d <dev> [ -r relay_path ] [ -o output ] [ -k ] [ -w time ]
+$ blktrace -d <dev> [ -r debug_path ] [ -o output ] [ -k ] [ -w time ]
[ -a action ] [ -A action mask ]
-d Use specified device. May also be given last after options.
- -r Path to mounted relayfs, defaults to /relay.
+ -r Path to mounted debugfs, defaults to /sys/kernel/debug.
-o File(s) to send output to.
-D Directory to prepend to output file names.
-k Kill running trace.
-A Give the trace mask directly as a number.
- -v Print program version info.
-b Sub buffer size in KiB.
-n Number of sub buffers.
+ -l Run in network listen mode (blktrace server)
+ -h Run in network client mode, connecting to the given host
+ -p Network port to use (default 8462)
+ -s Disable network client use of sendfile() to transfer data
+ -V Print program version info.
$ blkparse -i <input> [ -o <output> ] [ -b rb_batch ] [ -s ] [ -t ] [ -q ]
[ -w start:stop ] [ -f output format ] [ -F format spec ]
+ [ -d <binary> ]
-i Input file containing trace data, or '-' for stdin.
-D Directory to prepend to input file names.
-o Output file. If not given, output is stdout.
-b stdin read batching.
-s Show per-program io statistics.
- -n Hash processes by name, not pid.
+ -h Hash processes by name, not pid.
-t Track individual ios. Will tell you the time a request took to
get queued, to get dispatched, and to get completed.
-q Quiet. Don't display any stats at the end of the trace.
-w Only parse data between the given time interval in seconds. If
'start' isn't given, blkparse defaults the start time to 0.
+ -d Dump sorted data in binary format
-f Output format. Customize the output format. The format field
identifiers are:
%a - Action
%c - CPU ID
- %C - Task command name
+ %C - Task command (process) name
%d - Direction (r/w)
%D - Device number
%e - Error number
-F Format specification. The individual specifiers are:
- B - Back merge
+ A - Remap
+ B - Bounce
C - Complete
D - Issue
+ M - Back merge
F - Front merge
G - Get request
I - Insert
- M - Both front and back merge
P - Plug
Q - Queue
R - Requeue
W - Bounce
X - Split
- -m Print missing entries.
- -v Print program version info.
+ -v More verbose for marginal errors.
+ -V Print program version info.
$ verify_blkparse filename
the events in the file are correctly time ordered. If an entry
is found that isn't ordered, it's dumped to stdout.
+$ blkrawverify <dev> [<dev>...]
+
+ The blkrawverify utility can be used to verify data retrieved
+ via blktrace. It will check for valid event formats, forward
+ progressing sequence numbers and time stamps, also does reasonable
+ checks for other potential issues within invidividual events.
+
+ Errors found will be tracked in <dev>.verify.out.
If you want to do live tracing, you can pipe the data between blktrace
and blkparse:
This has a small risk of displaying some traces a little out of sync, since
it will do batch sorts of input events. Similarly, you can do traces over
-the network with eg netcat:
+the network. The network 'server' must run:
+
+% blktrace -l
+
+to listen to incoming blktrace connections, while the client should use
+
+% blktrace -d /dev/sda -h <server hostname>
+
+to connect and transfer data over the network.
+
-% blktrace -d /dev/sda -o - | netcat parsehost portno
-% netcat -l -p portno tracehost | blkparse -i -
+Documentation
+-------------
-Which will send the traces from tracehost to parsehost over the network on
-the defined port number.
+A users guide is distributed with the source. It is in latex, a
+'make docs' will build a PDF in doc/. You need tetex and latex installed
+to build the document.
Resources
-20050906, Jens Axboe <axboe@suse.de>
+2006-09-05, Jens Axboe <axboe@kernel.dk>
projects / blktrace.git / blobdiff