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      - Nblocks
  84                 %p      - PID
  85                 %P      - PDU
  86                 %s      - Sequence number
  87                 %S      - Sector number
  88                 %t      - Time (wallclock - nanoseconds)
  89                 %T      - Time (wallclock - seconds)
  90                 %u      - Time (processing - microseconds)
  91                 %U      - Unplug depth
  92
  93         -F Format specification. The individual specifiers are:
  94
  95                 B       - Back merge
  96                 C       - Complete
  97                 D       - Issue
  98                 F       - Front merge
  99                 G       - Get request
 100                 I       - Insert
 101                 M       - Both front and back merge
 102                 P       - Plug
 103                 Q       - Queue
 104                 R       - Requeue
 105                 S       - Sleep requests
 106                 T       - Unplug timer
 107                 U       - Unplug IO
 108                 W       - Bounce
 109                 X       - Split
 110
 111         -v Print program version info.
 112
 113 If you want to do live tracing, you can pipe the data between blktrace
 114 and blkparse:
 115
 116 % blktrace -d <device> -o - | blkparse -i -
 117
 118 This has a small risk of displaying some traces a little out of sync, since
 119 it will do batch sorts of input events. Similarly, you can do traces over
 120 the network with eg netcat:
 121
 122 % blktrace -d /dev/sda -o - | netcat parsehost portno
 123 % netcat -l -p portno tracehost | blkparse -i -
 124
 125 Which will send the traces from tracehost to parsehost over the network on
 126 the defined port number.
 127
 128
 129 Resources
 130 ---------
 131
 132 vger hosts a mailing list dedicated to btrace discussion and development.
 133 The list is called linux-btrace@vger.kernel.org, subscribe by sending
 134 a mail to majordomo@vger.kernel.org with 'subscribe linux-btrace' in
 135 the mail body.
 136
 137
 138
 139 20050906, Jens Axboe <axboe@suse.de>
 140