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         -l Run in network listen mode (blktrace server)
  64         -h Run in network client mode, connecting to the given host
  65         -p Network port to use (default 8462)
  66         -s Make the network client use sendfile() to transfer data
  67         -V Print program version info.
  68
  69 $ blkparse -i <input> [ -o <output> ] [ -b rb_batch ] [ -s ] [ -t ] [ -q ]
  70                       [ -w start:stop ] [ -f output format ] [ -F format spec ]
  71
  72         -i Input file containing trace data, or '-' for stdin.
  73         -D Directory to prepend to input file names.
  74         -o Output file. If not given, output is stdout.
  75         -b stdin read batching.
  76         -s Show per-program io statistics.
  77         -h Hash processes by name, not pid.
  78         -t Track individual ios. Will tell you the time a request took to
  79            get queued, to get dispatched, and to get completed.
  80         -q Quiet. Don't display any stats at the end of the trace.
  81         -w Only parse data between the given time interval in seconds. If
  82            'start' isn't given, blkparse defaults the start time to 0.
  83         -f Output format. Customize the output format. The format field
  84            identifiers are:
  85
  86                 %a      - Action
  87                 %c      - CPU ID
  88                 %C      - Task command name
  89                 %d      - Direction (r/w)
  90                 %D      - Device number
  91                 %e      - Error number
  92                 %M      - Major
  93                 %m      - Minor
  94                 %N      - Number of bytes
  95                 %n      - Number of sectors
  96                 %p      - PID
  97                 %P      - PDU
  98                 %s      - Sequence number
  99                 %S      - Sector number
 100                 %t      - Time (wallclock - nanoseconds)
 101                 %T      - Time (wallclock - seconds)
 102                 %u      - Time (processing - microseconds)
 103                 %U      - Unplug depth
 104
 105         -F Format specification. The individual specifiers are:
 106
 107                 A       - Remap
 108                 B       - Back merge
 109                 C       - Complete
 110                 D       - Issue
 111                 F       - Front merge
 112                 G       - Get request
 113                 I       - Insert
 114                 M       - Both front and back merge
 115                 P       - Plug
 116                 Q       - Queue
 117                 R       - Requeue
 118                 S       - Sleep requests
 119                 T       - Unplug timer
 120                 U       - Unplug IO
 121                 W       - Bounce
 122                 X       - Split
 123
 124         -v More verbose for marginal errors.
 125         -V Print program version info.
 126
 127 $ verify_blkparse filename
 128
 129         Verifies an output file from blkparse. All it does is check if
 130         the events in the file are correctly time ordered. If an entry
 131         is found that isn't ordered, it's dumped to stdout.
 132
 133 $ blkrawverify <dev> [<dev>...]
 134
 135         The blkrawverify utility can be used to verify data retrieved
 136         via blktrace. It will check for valid event formats, forward
 137         progressing sequence numbers and time stamps, also does reasonable
 138         checks for other potential issues within invidividual events.
 139
 140         Errors found will be tracked in <dev>.verify.out.
 141
 142 If you want to do live tracing, you can pipe the data between blktrace
 143 and blkparse:
 144
 145 % blktrace -d <device> -o - | blkparse -i -
 146
 147 This has a small risk of displaying some traces a little out of sync, since
 148 it will do batch sorts of input events. Similarly, you can do traces over
 149 the network. The network 'server' must run:
 150
 151 % blktrace -l
 152
 153 to listen to incoming blktrace connections, while the client should use
 154
 155 % blktrace -d /dev/sda -h <server hostname>
 156
 157 to connect and transfer data over the network.
 158
 159
 160 Documentation
 161 -------------
 162
 163 A users guide is distributed with the source. It is in latex, a
 164 'make docs' will build a PDF in doc/. You need tetex and latex installed
 165 to build the document.
 166
 167
 168 Resources
 169 ---------
 170
 171 vger hosts a mailing list dedicated to btrace discussion and development.
 172 The list is called linux-btrace@vger.kernel.org, subscribe by sending
 173 a mail to majordomo@vger.kernel.org with 'subscribe linux-btrace' in
 174 the mail body.
 175
 176
 177
 178 20051007, Jens Axboe <axboe@suse.de>
 179