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 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 (a] vger.kernel.org, subscribe by sending 177 a mail to majordomo (a] vger.kernel.org with 'subscribe linux-btrace' in 178 the mail body. 179 180 181 182 2006-09-05, Jens Axboe <axboe (a] kernel.dk> 183 184
