README

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