San Mehat | e20e134 | 2009-06-03 15:36:35 -0700 | [diff] [blame] | 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 | |
Wei Wang | c80018f | 2018-08-29 14:04:30 -0700 | [diff] [blame] | 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. |
San Mehat | e20e134 | 2009-06-03 15:36:35 -0700 | [diff] [blame] | 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 | |