README

   1 Block IO Tracing
   2 ----------------
   3
   4 Written by Jens Axboe <axboe@suse.de> (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
   8
   9 Requirements
  10 ------------
  11
  12 You need to be running a 2.6.14-rc3 kernel or newer, with the blk-trace patch
  13 included in this repository. If you forgot where you got it, the url is:
  14
  15 rsync://rsync.kernel.org/pub/scm/linux/kernel/git/axboe/blktrace.git
  16
  17 If you don't have git, you can get hourly snapshots from:
  18
  19 http://www.kernel.org/pub/linux/kernel/people/axboe/blktrace/
  20
  21 The snapshots include the full git object database as well. kernel.org has
  22 excessively long mirror times, so if you have git installed, you can pull
  23 the master tree from:
  24
  25 git://brick.kernel.dk/data/git/blktrace.git
  26
  27 For browsing the repo over http and viewing history etc, you can direct
  28 your browser to:
  29
  30 http://brick.kernel.dk/git
  31
  32
  33 Usage
  34 -----
  35
  36 $ blktrace -d <dev> [ -r relay_path ] [ -o output ] [ -k ] [ -w time ]
  37                     [ -a action ] [ -A action mask ]
  38
  39         -d Use specified device. May also be given last after options.
  40         -r Path to mounted relayfs, defaults to /relay.
  41         -o File(s) to send output to.
  42         -D Directory to prepend to output file names.
  43         -k Kill running trace.
  44         -w Stop after defined time, in seconds.
  45         -a Only trace specific actions (use more -a options to add actions).
  46            Available actions are:
  47
  48                 READ
  49                 WRITE
  50                 BARRIER
  51                 SYNC
  52                 QUEUE
  53                 REQUEUE
  54                 ISSUE
  55                 COMPLETE
  56                 FS
  57                 PC
  58
  59         -A Give the trace mask directly as a number.
  60
  61         -b Sub buffer size in KiB.
  62         -n Number of sub buffers.
  63         -V Print program version info.
  64
  65 $ blkparse -i <input> [ -o <output> ] [ -b rb_batch ] [ -s ] [ -t ] [ -q ]
  66                       [ -w start:stop ] [ -f output format ] [ -F format spec ]
  67
  68         -i Input file containing trace data, or '-' for stdin.
  69         -D Directory to prepend to input file names.
  70         -o Output file. If not given, output is stdout.
  71         -b stdin read batching.
  72         -s Show per-program io statistics.
  73         -h Hash processes by name, not pid.
  74         -t Track individual ios. Will tell you the time a request took to
  75            get queued, to get dispatched, and to get completed.
  76         -q Quiet. Don't display any stats at the end of the trace.
  77         -w Only parse data between the given time interval in seconds. If
  78            'start' isn't given, blkparse defaults the start time to 0.
  79         -f Output format. Customize the output format. The format field
  80            identifiers are:
  81
  82                 %a      - Action
  83                 %c      - CPU ID
  84                 %C      - Task command name
  85                 %d      - Direction (r/w)
  86                 %D      - Device number
  87                 %e      - Error number
  88                 %M      - Major
  89                 %m      - Minor
  90                 %N      - Number of bytes
  91                 %n      - Number of sectors
  92                 %p      - PID
  93                 %P      - PDU
  94                 %s      - Sequence number
  95                 %S      - Sector number
  96                 %t      - Time (wallclock - nanoseconds)
  97                 %T      - Time (wallclock - seconds)
  98                 %u      - Time (processing - microseconds)
  99                 %U      - Unplug depth
 100
 101         -F Format specification. The individual specifiers are:
 102
 103                 A       - Remap
 104                 B       - Back merge
 105                 C       - Complete
 106                 D       - Issue
 107                 F       - Front merge
 108                 G       - Get request
 109                 I       - Insert
 110                 M       - Both front and back merge
 111                 P       - Plug
 112                 Q       - Queue
 113                 R       - Requeue
 114                 S       - Sleep requests
 115                 T       - Unplug timer
 116                 U       - Unplug IO
 117                 W       - Bounce
 118                 X       - Split
 119
 120         -v More verbose for marginal errors.
 121         -V Print program version info.
 122
 123 $ verify_blkparse filename
 124
 125         Verifies an output file from blkparse. All it does is check if
 126         the events in the file are correctly time ordered. If an entry
 127         is found that isn't ordered, it's dumped to stdout.
 128
 129 $ blkrawverify <dev> [<dev>...]
 130
 131         The blkrawverify utility can be used to verify data retrieved
 132         via blktrace. It will check for valid event formats, forward
 133         progressing sequence numbers and time stamps, also does reasonable
 134         checks for other potential issues within invidividual events.
 135
 136         Errors found will be tracked in <dev>.verify.out.
 137
 138 If you want to do live tracing, you can pipe the data between blktrace
 139 and blkparse:
 140
 141 % blktrace -d <device> -o - | blkparse -i -
 142
 143 This has a small risk of displaying some traces a little out of sync, since
 144 it will do batch sorts of input events. Similarly, you can do traces over
 145 the network with eg netcat:
 146
 147 % blktrace -d /dev/sda -o - | netcat parsehost portno
 148 % netcat -l -p portno tracehost | blkparse -i -
 149
 150 Which will send the traces from tracehost to parsehost over the network on
 151 the defined port number.
 152
 153 Documentation
 154 -------------
 155
 156 A users guide is distributed with the source. It is in latex, a
 157 'make docs' will build a PDF in doc/. You need tetex and latex installed
 158 to build the document.
 159
 160
 161 Resources
 162 ---------
 163
 164 vger hosts a mailing list dedicated to btrace discussion and development.
 165 The list is called linux-btrace@vger.kernel.org, subscribe by sending
 166 a mail to majordomo@vger.kernel.org with 'subscribe linux-btrace' in
 167 the mail body.
 168
 169
 170
 171 20051007, Jens Axboe <axboe@suse.de>
 172