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 kill utility invocation).
  70 There are two ways to modify this:
  71
  72 .TP 5
  73   1.
  74 You may utilise the blktrace utility itself to kill
  75 a running trace -- via the \fB\-k\fR option.
  76
  77 .TP 5
  78   2.
  79 You can specify a run-time duration for blktrace via the
  80 \fB\-w\fR option -- then blktrace will run for the specified number
  81 of seconds, and then halt.
  82
  83
  84 .SH OPTIONS
  85
  86 \-A \fIhex-mask\fR
  87 .br
  88 \-\-set-mask=\fIhex-mask\fR
  89 .RS
  90 Set filter mask to \fIhex-mask\fR (see below for masks)
  91 .RE
  92
  93 \-a \fImask\fR
  94 .br
  95 \-\-act-mask=\fImask\fR
  96 .RS
  97 Add \fImask\fR to current filter (see below for masks)
  98 .RE
  99
 100 \-b \fIsize\fR
 101 .br
 102 \-\-buffer\-size=\fIsize\fR
 103 .RS
 104 Specifies buffer size for event extraction (scaled by 1024). The default
 105 buffer size is 512KiB.
 106 .RE
 107
 108 \-d \fIdev\fR
 109 .br
 110 \-\-dev=\fIdev\fR
 111 .RS
 112 Adds \fIdev\fR as a device to trace
 113 .RE
 114
 115 \-I \fIfile\fR
 116 .br
 117 \-\-input-devs=\fIfile\fR
 118 .RS
 119 Adds the devices found in \fIfile\fR as devices to trace
 120 .RE
 121
 122 \-k
 123 .br
 124 \-\-kill
 125 .RS
 126 Kill on-going trace
 127 .RE
 128
 129 \-n \fInum\-sub\fR
 130 .br
 131 \-\-num\-sub=\fInum-sub\fR
 132 .RS
 133 Specifies number of buffers to use. blktrace defaults to 4 sub buffers.
 134 .RE
 135
 136 \-o \fIfile\fR
 137 .br
 138 \-\-output=\fIfile\fR
 139 .RS
 140 Prepend \fIfile\fR to output file name(s)
 141 .RE
 142
 143 \-r \fIrel-path\fR
 144 .br
 145 \-\-relay=\fIrel-path\fR
 146 .RS
 147 Specifies debugfs mount point
 148 .RE
 149
 150 \-V
 151 .br
 152 \-\-version
 153 Outputs version
 154 .RE
 155
 156 \-w \fIseconds\fR
 157 .br
 158 \-\-stopwatch=\fIseconds\fR
 159 .RS
 160 Sets run time to the number of seconds specified
 161 .RE
 162
 163
 164 .SH FILTER MASKS
 165 The following masks may be passed with the \fI\-a\fR command line
 166 option, multiple filters may be combined via multiple \fI\-a\fR command
 167 line options.
 168
 169 .RS
 170 \fIbarrier\fR: barrier attribute
 171 .br
 172 \fIcomplete\fR: completed} by driver
 173 .br
 174 \fIfs\fR: requests
 175 .br
 176 \fIissue\fR: issued to driver
 177 .br
 178 \fIpc\fR: packet command events
 179 .br
 180 \fIqueue\fR: queue operations
 181 .br
 182 \fIread\fR: read traces
 183 .br
 184 \fIrequeue\fR: requeue operations
 185 .br
 186 \fIsync\fR: synchronous attribute
 187 .br
 188 \fIwrite\fR: write traces
 189 .RE
 190
 191
 192 .SH REQUEST TYPES
 193 blktrace distinguishes between two types of block layer requests, file system
 194 and SCSI commands. The former are dubbed \fBfs\fR requests, the latter
 195 \fBpc\fR requests. File system requests are normal read/write operations, i.e.
 196 any type of read or write from a specific disk location at a given size. These
 197 requests typically originate from a user process, but they may also be
 198 initiated by the vm flushing dirty data to disk or the file system syncing a
 199 super or journal block to disk. \fBpc\fR requests are SCSI commands. blktrace
 200 sends the command data block as a payload so that blkparse can decode it.
 201
 202
 203 .SH EXAMPLES
 204 To trace the i/o on the device \fI/dev/hda\fR and parse the output to human
 205 readable form, use the following command:
 206
 207     % blktrace \-d /dev/sda \-o \- | blkparse \-i \-
 208
 209 This same behaviour can be achieve with the convenience script \fIbtrace\fR.
 210 The command
 211
 212     % btrace /dev/sda
 213
 214 has exactly the same effect as the previous command. See \fIbtrace\fR (8) for
 215 more information.
 216
 217 To trace the i/o on a device and save the output for later processing with
 218 \fIblkparse\fR, use \fIblktrace\fR like this:
 219
 220     % blktrace /dev/sda /dev/sdb
 221
 222 This will trace i/o on the devices \fI/dev/sda\fR and \fI/dev/sdb\fR and save
 223 the recorded information in the files \fIsda\fR and \fIsdb\fR in the current
 224 directory, for the two different devices, respectively.  This trace
 225 information can later be parsed by the \fIblkparse\fR utility:
 226
 227     % blkparse sda sdb
 228
 229 which will output the previously recorded tracing information in human
 230 readable form to stdout.  See \fIblkparse\fR (1) for more information.
 231
 232
 233 .SH AUTHORS
 234 blktrace was written by Jens Axboe, Alan D. Brunelle and Nathan Scott.  This
 235 man page was created from the blktrace documentation by Bas Zoetekouw.
 236
 237
 238 .SH "REPORTING BUGS"
 239 Report bugs to <linux\-btrace@vger.kernel.org>
 240
 241 .SH COPYRIGHT
 242 Copyright \(co 2006 Jens Axboe, Alan D. Brunelle and Nathan Scott.
 243 .br
 244 This is free software.  You may redistribute copies of it under the terms of
 245 the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
 246 There is NO WARRANTY, to the extent permitted by law.
 247 .br
 248 This manual page was created for Debian by Bas Zoetekouw.  It was derived from
 249 the documentation provided by the authors and it may be used, distributed and
 250 modified under the terms of the GNU General Public License, version 2.
 251 .br
 252 On Debian systems, the text of the GNU General Public License can be found in
 253 /usr/share/common\-licenses/GPL\-2.
 254
 255 .SH "SEE ALSO"
 256 btrace (8), blkparse (1), verify_blkparse (1), blkrawverify (1), btt (1)
 257