| 1 | .TH BLKTRACE 8 "March 6, 2007" "blktrace git\-20070306202522" "" |
| 2 | |
| 3 | |
| 4 | .SH NAME |
| 5 | blktrace \- generate traces of the i/o traffic on block devices |
| 6 | |
| 7 | |
| 8 | .SH SYNOPSIS |
| 9 | .B blktrace \-d \fIdev\fR [ \-r \fIdebugfs_path\fR ] [ \-o \fIoutput\fR ] [\-k ] [ \-w \fItime\fR ] [ \-a \fIaction\fR ] [ \-A \fIaction_mask\fR ] [ \-v ] |
| 10 | .br |
| 11 | |
| 12 | |
| 13 | .SH DESCRIPTION |
| 14 | blktrace is a block layer IO tracing mechanism which provides detailed |
| 15 | information about request queue operations up to user space. There are three |
| 16 | major components: a kernel component, a utility to record the i/o trace |
| 17 | information for the kernel to user space, and utilities to analyse and view the |
| 18 | trace information. This man page describes blktrace, which records the i/o event |
| 19 | trace information for a specific block device to a file. |
| 20 | |
| 21 | The \fBblktrace\fR utility extracts event traces from the kernel (via |
| 22 | the relaying through the debug file system). Some background details |
| 23 | concerning the run\-time behaviour of blktrace will help to understand some |
| 24 | of the more arcane command line options: |
| 25 | |
| 26 | .TP 2 |
| 27 | \- |
| 28 | blktrace receives data from the kernel in buffers passed up through the |
| 29 | debug file system (relay). Each device being traced has a file created in |
| 30 | the mounted directory for the debugfs, which defaults to |
| 31 | \fI/sys/kernel/debug\fR \-\- this can be overridden with the \fB\-r\fR command |
| 32 | line argument. |
| 33 | |
| 34 | .TP 2 |
| 35 | \- |
| 36 | blktrace defaults to collecting all events that can be traced. To |
| 37 | limit the events being captured, you can specify one or more filter masks |
| 38 | via the \fB\-a\fR option. |
| 39 | |
| 40 | Alternatively, one may specify the entire mask utilising a hexadecimal |
| 41 | value that is version\-specific. (Requires understanding of the internal |
| 42 | representation of the filter mask.) |
| 43 | |
| 44 | .TP 2 |
| 45 | \- |
| 46 | As noted above, the events are passed up via a series of buffers stored |
| 47 | into debugfs files. The size and number of buffers can be specified via |
| 48 | the \fB\-b\fR and \fB\-n\fR arguments respectively. |
| 49 | |
| 50 | .TP 2 |
| 51 | \- |
| 52 | blktrace stores the extracted data into files stored in the |
| 53 | local directory. The format of the file names is (by default) |
| 54 | \fBdevice\fR.\fBblktrace\fR.\fBcpu\fR, where \fBdevice\fR is the base |
| 55 | device name (e.g, if we are tracing /dev/sda, the base device name would |
| 56 | be \fBsda\fR); and \fBcpu\fR identifies a CPU for the event stream. |
| 57 | |
| 58 | The \fBdevice\fR portion of the event file name can be changed via |
| 59 | the \fB\-o\fR option. |
| 60 | |
| 61 | .TP 2 |
| 62 | \- |
| 63 | blktrace may also be run concurrently with blkparse to produce |
| 64 | \fBlive\fR output \-\- to do this specify \fB\-o \-\fR for blktrace. |
| 65 | |
| 66 | .TP 2 |
| 67 | \- |
| 68 | The default behaviour for blktrace is to run forever until explicitly |
| 69 | killed by the user (via a control-C, or sending SIGINT signal to the |
| 70 | process via invocation the kill (1) utility). Also you can specify a |
| 71 | run-time duration for blktrace via the \fB\-w\fR option -- then |
| 72 | blktrace will run for the specified number of seconds, and then halt. |
| 73 | |
| 74 | |
| 75 | .SH OPTIONS |
| 76 | |
| 77 | \-A \fIhex-mask\fR |
| 78 | .br |
| 79 | \-\-set-mask=\fIhex-mask\fR |
| 80 | .RS |
| 81 | Set filter mask to \fIhex-mask\fR (see below for masks) |
| 82 | .RE |
| 83 | |
| 84 | \-a \fImask\fR |
| 85 | .br |
| 86 | \-\-act-mask=\fImask\fR |
| 87 | .RS |
| 88 | Add \fImask\fR to current filter (see below for masks) |
| 89 | .RE |
| 90 | |
| 91 | \-b \fIsize\fR |
| 92 | .br |
| 93 | \-\-buffer\-size=\fIsize\fR |
| 94 | .RS |
| 95 | Specifies buffer size for event extraction (scaled by 1024). The default |
| 96 | buffer size is 512KiB. |
| 97 | .RE |
| 98 | |
| 99 | \-d \fIdev\fR |
| 100 | .br |
| 101 | \-\-dev=\fIdev\fR |
| 102 | .RS |
| 103 | Adds \fIdev\fR as a device to trace |
| 104 | .RE |
| 105 | |
| 106 | \-I \fIfile\fR |
| 107 | .br |
| 108 | \-\-input-devs=\fIfile\fR |
| 109 | .RS |
| 110 | Adds the devices found in \fIfile\fR as devices to trace |
| 111 | .RE |
| 112 | |
| 113 | \-n \fInum\-sub\fR |
| 114 | .br |
| 115 | \-\-num\-sub=\fInum-sub\fR |
| 116 | .RS |
| 117 | Specifies number of buffers to use. blktrace defaults to 4 sub buffers. |
| 118 | .RE |
| 119 | |
| 120 | \-o \fIfile\fR |
| 121 | .br |
| 122 | \-\-output=\fIfile\fR |
| 123 | .RS |
| 124 | Prepend \fIfile\fR to output file name(s) |
| 125 | .RE |
| 126 | |
| 127 | \-r \fIrel-path\fR |
| 128 | .br |
| 129 | \-\-relay=\fIrel-path\fR |
| 130 | .RS |
| 131 | Specifies debugfs mount point |
| 132 | .RE |
| 133 | |
| 134 | \-V |
| 135 | .br |
| 136 | \-\-version |
| 137 | Outputs version |
| 138 | .RE |
| 139 | |
| 140 | \-w \fIseconds\fR |
| 141 | .br |
| 142 | \-\-stopwatch=\fIseconds\fR |
| 143 | .RS |
| 144 | Sets run time to the number of seconds specified |
| 145 | .RE |
| 146 | |
| 147 | |
| 148 | .SH FILTER MASKS |
| 149 | The following masks may be passed with the \fI\-a\fR command line |
| 150 | option, multiple filters may be combined via multiple \fI\-a\fR command |
| 151 | line options. |
| 152 | |
| 153 | .RS |
| 154 | \fIbarrier\fR: barrier attribute |
| 155 | .br |
| 156 | \fIcomplete\fR: completed by driver |
| 157 | .br |
| 158 | \fIfs\fR: requests |
| 159 | .br |
| 160 | \fIissue\fR: issued to driver |
| 161 | .br |
| 162 | \fIpc\fR: packet command events |
| 163 | .br |
| 164 | \fIqueue\fR: queue operations |
| 165 | .br |
| 166 | \fIread\fR: read traces |
| 167 | .br |
| 168 | \fIrequeue\fR: requeue operations |
| 169 | .br |
| 170 | \fIsync\fR: synchronous attribute |
| 171 | .br |
| 172 | \fIwrite\fR: write traces |
| 173 | .br |
| 174 | \fInotify\fR: trace messages |
| 175 | .RE |
| 176 | |
| 177 | |
| 178 | .SH REQUEST TYPES |
| 179 | blktrace distinguishes between two types of block layer requests, file system |
| 180 | and SCSI commands. The former are dubbed \fBfs\fR requests, the latter |
| 181 | \fBpc\fR requests. File system requests are normal read/write operations, i.e. |
| 182 | any type of read or write from a specific disk location at a given size. These |
| 183 | requests typically originate from a user process, but they may also be |
| 184 | initiated by the vm flushing dirty data to disk or the file system syncing a |
| 185 | super or journal block to disk. \fBpc\fR requests are SCSI commands. blktrace |
| 186 | sends the command data block as a payload so that blkparse can decode it. |
| 187 | |
| 188 | |
| 189 | .SH EXAMPLES |
| 190 | To trace the i/o on the device \fI/dev/hda\fR and parse the output to human |
| 191 | readable form, use the following command: |
| 192 | |
| 193 | % blktrace \-d /dev/sda \-o \- | blkparse \-i \- |
| 194 | |
| 195 | This same behaviour can be achieve with the convenience script \fIbtrace\fR. |
| 196 | The command |
| 197 | |
| 198 | % btrace /dev/sda |
| 199 | |
| 200 | has exactly the same effect as the previous command. See \fIbtrace\fR (8) for |
| 201 | more information. |
| 202 | |
| 203 | To trace the i/o on a device and save the output for later processing with |
| 204 | \fIblkparse\fR, use \fIblktrace\fR like this: |
| 205 | |
| 206 | % blktrace /dev/sda /dev/sdb |
| 207 | |
| 208 | This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save |
| 209 | the recorded information in the files \fIsda\fR and \fIsdb\fR in the current |
| 210 | directory, for the two different devices, respectively. This trace |
| 211 | information can later be parsed by the \fIblkparse\fR utility: |
| 212 | |
| 213 | % blkparse sda sdb |
| 214 | |
| 215 | which will output the previously recorded tracing information in human |
| 216 | readable form to stdout. See \fIblkparse\fR (1) for more information. |
| 217 | |
| 218 | |
| 219 | .SH AUTHORS |
| 220 | blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott. This |
| 221 | man page was created from the blktrace documentation by Bas Zoetekouw. |
| 222 | |
| 223 | |
| 224 | .SH "REPORTING BUGS" |
| 225 | Report bugs to <linux\-btrace@vger.kernel.org> |
| 226 | |
| 227 | .SH COPYRIGHT |
| 228 | Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott. |
| 229 | .br |
| 230 | This is free software. You may redistribute copies of it under the terms of |
| 231 | the GNU General Public License <http://www.gnu.org/licenses/gpl.html>. |
| 232 | There is NO WARRANTY, to the extent permitted by law. |
| 233 | .br |
| 234 | This manual page was created for Debian by Bas Zoetekouw. It was derived from |
| 235 | the documentation provided by the authors and it may be used, distributed and |
| 236 | modified under the terms of the GNU General Public License, version 2. |
| 237 | .br |
| 238 | On Debian systems, the text of the GNU General Public License can be found in |
| 239 | /usr/share/common\-licenses/GPL\-2. |
| 240 | |
| 241 | .SH "SEE ALSO" |
| 242 | btrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1) |
| 243 | |