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