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