doc/blktrace.8

   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\-buffers=\fInum-sub\fR
 116 .RS
 117 Specifies number of buffers to use. blktrace defaults to 4 sub buffers.
 118 .RE
 119
 120 \-l
 121 .br
 122 \-\-listen
 123 .RS
 124 Run in network listen mode (blktrace server)
 125 .RE
 126
 127 \-h \fIhostname\fR
 128 .br
 129 \-\-host=\fIhostname\fR
 130 .RS
 131 Run in network client mode, connecting to the given host
 132 .RE
 133
 134 \-p \fInumber\fR
 135 .br
 136 \-\-port=\fInumber\fR
 137 .RS
 138 Network port to use (default 8462)
 139 .RE
 140
 141 \-s
 142 .br
 143 \-\-no\-sendfile
 144 .RS
 145 Make the network client NOT use sendfile() to transfer data
 146 .RE
 147
 148 \-o \fIbasename\fR
 149 .br
 150 \-\-output=\fIbasename\fR
 151 .RS
 152 Specifies base name for input files. Default is device.blktrace.cpu.
 153 Specifying -o - runs in live mode with blkparse (writing data to standard out).
 154 .RE
 155
 156 \-D \fIdir\fR
 157 .br
 158 \-\-output\-dir=\fIdir\fR
 159 .RS
 160 Prepend \fIfile\fR to output file name(s)
 161
 162 This only works when supplying a single device, or when piping the output
 163 via "-o -" with multiple devices.
 164 .RE
 165
 166 \-r \fIrel-path\fR
 167 .br
 168 \-\-relay=\fIrel-path\fR
 169 .RS
 170 Specifies debugfs mount point
 171 .RE
 172
 173 \-v
 174 .br
 175 \-\-version
 176 .RS
 177 Outputs version
 178 .RE
 179
 180 \-V
 181 .br
 182 \-\-version
 183 .RS
 184 Outputs version
 185 .RE
 186
 187 \-w \fIseconds\fR
 188 .br
 189 \-\-stopwatch=\fIseconds\fR
 190 .RS
 191 Sets run time to the number of seconds specified
 192 .RE
 193
 194
 195 .SH FILTER MASKS
 196 The following masks may be passed with the \fI\-a\fR command line
 197 option, multiple filters may be combined via multiple \fI\-a\fR command
 198 line options.
 199
 200 .RS
 201 \fIbarrier\fR: barrier attribute
 202 .br
 203 \fIcomplete\fR: completed by driver
 204 .br
 205 \fIdiscard\fR: discard / trim traces
 206 .br
 207 \fIfs\fR: requests
 208 .br
 209 \fIissue\fR: issued to driver
 210 .br
 211 \fIpc\fR: packet command events
 212 .br
 213 \fIqueue\fR: queue operations
 214 .br
 215 \fIread\fR: read traces
 216 .br
 217 \fIrequeue\fR: requeue operations
 218 .br
 219 \fIsync\fR: synchronous attribute
 220 .br
 221 \fIwrite\fR: write traces
 222 .br
 223 \fInotify\fR: trace messages
 224 .br
 225 \fIdrv_data\fR: additional driver specific trace
 226 .RE
 227
 228
 229 .SH REQUEST TYPES
 230 blktrace distinguishes between two types of block layer requests, file system
 231 and SCSI commands. The former are dubbed \fBfs\fR requests, the latter
 232 \fBpc\fR requests. File system requests are normal read/write operations, i.e.
 233 any type of read or write from a specific disk location at a given size. These
 234 requests typically originate from a user process, but they may also be
 235 initiated by the vm flushing dirty data to disk or the file system syncing a
 236 super or journal block to disk. \fBpc\fR requests are SCSI commands. blktrace
 237 sends the command data block as a payload so that blkparse can decode it.
 238
 239
 240 .SH EXAMPLES
 241 To trace the i/o on the device \fI/dev/sda\fR and parse the output to human
 242 readable form, use the following command:
 243
 244     % blktrace \-d /dev/sda \-o \- | blkparse \-i \-
 245
 246 This same behaviour can be achieve with the convenience script \fIbtrace\fR.
 247 The command
 248
 249     % btrace /dev/sda
 250
 251 has exactly the same effect as the previous command. See \fIbtrace\fR (8) for
 252 more information.
 253
 254 To trace the i/o on a device and save the output for later processing with
 255 \fIblkparse\fR, use \fIblktrace\fR like this:
 256
 257     % blktrace /dev/sda /dev/sdb
 258
 259 This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save
 260 the recorded information in the files \fIsda\fR and \fIsdb\fR in the current
 261 directory, for the two different devices, respectively.  This trace
 262 information can later be parsed by the \fIblkparse\fR utility:
 263
 264     % blkparse sda sdb
 265
 266 which will output the previously recorded tracing information in human
 267 readable form to stdout.  See \fIblkparse\fR (1) for more information.
 268
 269
 270 .SH AUTHORS
 271 blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.  This
 272 man page was created from the blktrace documentation by Bas Zoetekouw.
 273
 274
 275 .SH "REPORTING BUGS"
 276 Report bugs to <linux\-btrace@vger.kernel.org>
 277
 278 .SH COPYRIGHT
 279 Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
 280 .br
 281 This is free software.  You may redistribute copies of it under the terms of
 282 the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
 283 There is NO WARRANTY, to the extent permitted by law.
 284 .br
 285 This manual page was created for Debian by Bas Zoetekouw.  It was derived from
 286 the documentation provided by the authors and it may be used, distributed and
 287 modified under the terms of the GNU General Public License, version 2.
 288 .br
 289 On Debian systems, the text of the GNU General Public License can be found in
 290 /usr/share/common\-licenses/GPL\-2.
 291
 292 .SH "SEE ALSO"
 293 btrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)
 294