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-rc2 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
  28 Usage
  29 -----
  30
  31 $ blktrace -d <dev> [ -r relay_path ] [ -o output ] [ -k ] [ -w time ]
  32                     [ -a action ] [ -A action mask ]
  33
  34         -d Use specified device. May also be given last after options.
  35         -r Path to mounted relayfs, defaults to /relay.
  36         -o File(s) to send output to.
  37         -k Kill running trace.
  38         -w Stop after defined time, in seconds.
  39         -a Only trace specific actions (use more -a options to add actions).
  40            Available actions are:
  41
  42                 READ
  43                 WRITE
  44                 BARRIER
  45                 SYNC
  46                 QUEUE
  47                 REQUEUE
  48                 ISSUE
  49                 COMPLETE
  50                 FS
  51                 PC
  52
  53         -A Give the trace mask directly as a number.
  54
  55         -v Print program version info.
  56         -b Sub buffer size in KiB.
  57         -n Number of sub buffers.
  58
  59 $ blkparse -i <input> [ -o <output> ] [ -b rb_batch ] [ -s ] [ -t ] [ -q ]
  60                       [ -w start:stop ] [ -f output format ] [ -F format spec ]
  61
  62         -i Input file containing trace data, or '-' for stdin.
  63         -o Output file. If not given, output is stdout.
  64         -b stdin read batching.
  65         -s Show per-program io statistics.
  66         -n Hash processes by name, not pid.
  67         -t Track individual ios. Will tell you the time a request took to
  68            get queued, to get dispatched, and to get completed.
  69         -q Quiet. Don't display any stats at the end of the trace.
  70         -w Only parse data between the given time interval in seconds. If
  71            'start' isn't given, blkparse defaults the start time to 0.
  72         -f Output format. Customize the output format. The format field
  73            identifiers are:
  74
  75                 %a      - Action
  76                 %c      - CPU ID
  77                 %C      - Task command name
  78                 %d      - Direction (r/w)
  79                 %D      - Device number
  80                 %e      - Error number
  81                 %M      - Major
  82                 %m      - Minor
  83                 %N      - Number of bytes
  84                 %n      - Number of sectors
  85                 %p      - PID
  86                 %P      - PDU
  87                 %s      - Sequence number
  88                 %S      - Sector number
  89                 %t      - Time (wallclock - nanoseconds)
  90                 %T      - Time (wallclock - seconds)
  91                 %u      - Time (processing - microseconds)
  92                 %U      - Unplug depth
  93
  94         -F Format specification. The individual specifiers are:
  95
  96                 B       - Back merge
  97                 C       - Complete
  98                 D       - Issue
  99                 F       - Front merge
 100                 G       - Get request
 101                 I       - Insert
 102                 M       - Both front and back merge
 103                 P       - Plug
 104                 Q       - Queue
 105                 R       - Requeue
 106                 S       - Sleep requests
 107                 T       - Unplug timer
 108                 U       - Unplug IO
 109                 W       - Bounce
 110                 X       - Split
 111
 112         -v Print program version info.
 113
 114 If you want to do live tracing, you can pipe the data between blktrace
 115 and blkparse:
 116
 117 % blktrace -d <device> -o - | blkparse -i -
 118
 119 This has a small risk of displaying some traces a little out of sync, since
 120 it will do batch sorts of input events. Similarly, you can do traces over
 121 the network with eg netcat:
 122
 123 % blktrace -d /dev/sda -o - | netcat parsehost portno
 124 % netcat -l -p portno tracehost | blkparse -i -
 125
 126 Which will send the traces from tracehost to parsehost over the network on
 127 the defined port number.
 128
 129
 130 Resources
 131 ---------
 132
 133 vger hosts a mailing list dedicated to btrace discussion and development.
 134 The list is called linux-btrace@vger.kernel.org, subscribe by sending
 135 a mail to majordomo@vger.kernel.org with 'subscribe linux-btrace' in
 136 the mail body.
 137
 138
 139
 140 20050906, Jens Axboe <axboe@suse.de>
 141