1 Block IO Tracing 2 ---------------- 3 4 Written by Jens Axboe <axboe (a] kernel.dk> (initial version and kernel support), 5 Alan D. Brunelle (threading and splitup into two seperate programs), 6 Nathan Scott <nathans (a] sgi.com> (bug fixes, process names, multiple devices) 7 Also thanks to Tom Zanussi <zanussi (a] 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 (a] vger.kernel.org, subscribe by sending 179 a mail to majordomo (a] vger.kernel.org with 'subscribe linux-btrace' in 180 the mail body. 181 182 183 184 2006-09-05, Jens Axboe <axboe (a] kernel.dk> 185 186
