Block IO Tracing
----------------
-Written by Jens Axboe <axboe@suse.de> (initial version and kernel support) and
-Alan D. Brunelle (threading and splitup into two seperate programs).
+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.13-mm1 kernel 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.
+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://git.kernel.dk/blktrace.git
+
+For browsing the repo over http and viewing history etc, you can direct
+your browser to:
+
+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> [-o <output> -a <trace> [-a <trace>]]
- -a <trace> is one of: (use multiple -a options to get more)
+$ 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 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.
+ -w Stop after defined time, in seconds.
+ -a Only trace specific actions (use more -a options to add actions).
+ Available actions are:
+
READ
WRITE
BARRIER
COMPLETE
FS
PC
- --- run task to generate load to be traced ---
- <SIGINT to kill>
- --- Generates:
- <output>_out.[0..ncpus] : Contains binary trace data
-
- % blkparse -i <input> [-o <output>]
- --- Generates:
- <output>_log.[0..ncpus] : Contains formatted trace data, if
- output logging is added with the -o option.
- Merged formatted trace data to stdout
+ -A Give the trace mask directly as a number.
+
+ -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.
+ -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 (process) name
+ %d - Direction (r/w)
+ %D - Device number
+ %e - Error number
+ %M - Major
+ %m - Minor
+ %N - Number of bytes
+ %n - Number of sectors
+ %p - PID
+ %P - PDU
+ %s - Sequence number
+ %S - Sector number
+ %t - Time (wallclock - nanoseconds)
+ %T - Time (wallclock - seconds)
+ %u - Time (processing - microseconds)
+ %U - Unplug depth
+
+ -F Format specification. The individual specifiers are:
+
+ A - Remap
+ B - Bounce
+ C - Complete
+ D - Issue
+ M - Back merge
+ F - Front merge
+ G - Get request
+ I - Insert
+ P - Plug
+ Q - Queue
+ R - Requeue
+ S - Sleep requests
+ T - Unplug timer
+ U - Unplug IO
+ W - Bounce
+ X - Split
+
+ -v More verbose for marginal errors.
+ -V Print program version info.
+
+$ verify_blkparse filename
+
+ Verifies an output file from blkparse. All it does is check if
+ 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.
+
+
+Documentation
+-------------
+
+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
+---------
-% blktrace -d /dev/sda -o - | netcat parsehost portno
-% netcat -l -p portno tracehost | blkparse -i -
+vger hosts a mailing list dedicated to btrace discussion and development.
+The list is called linux-btrace@vger.kernel.org, subscribe by sending
+a mail to majordomo@vger.kernel.org with 'subscribe linux-btrace' in
+the mail body.
-Which will send the traces from tracehost to parsehost over the network on
-the defined port number.
-20050906, Jens Axboe <axboe@suse.de>
+2006-09-05, Jens Axboe <axboe@kernel.dk>
projects / blktrace.git / blobdiff