# blktrace

## NAME



           blktrace - generate traces of the i/o traffic on block devices
    


## SYNOPSIS



           **blktrace -d** _dev_ [ -r _debugfs_path_ ] [ -o _output_ ] [ -w _time_ ] [ -a
           _action_ ] [ -A _action_mask_ ] [ -v ]
    


## DESCRIPTION



           blktrace is a block layer IO tracing mechanism which provides
           detailed information about request queue operations up to user
           space. There are three major components: a kernel component, a
           utility to record the i/o trace information for the kernel to user
           space, and utilities to analyse and view the trace information.
           This man page describes blktrace, which records the i/o event
           trace information for a specific block device to a file.
    
           The **blktrace** utility extracts event traces from the kernel (via
           the relaying through the debug file system). Some background
           details concerning the run-time behaviour of blktrace will help to
           understand some of the more arcane command line options:
    
           - blktrace receives data from the kernel in buffers passed up
             through the debug file system (relay). Each device being traced
             has a file created in the mounted directory for the debugfs,
             which defaults to _/sys/kernel/debug_ -- this can be overridden
             with the **-r** command line argument.
    
           - blktrace defaults to collecting all events that can be traced.
             To limit the events being captured, you can specify one or more
             filter masks via the **-a** option.
    
             Alternatively, one may specify the entire mask utilising a
             hexadecimal value that is version-specific. (Requires
             understanding of the internal representation of the filter
             mask.)
    
           - As noted above, the events are passed up via a series of buffers
             stored into debugfs files. The size and number of buffers can be
             specified via the **-b** and **-n** arguments respectively.
    
           - blktrace stores the extracted data into files stored in the
             local directory. The format of the file names is (by default)
             **device**.**blktrace**.**cpu** , where **device** is the base device name (e.g,
             if we are tracing /dev/sda, the base device name would be **sda**);
             and **cpu** identifies a CPU for the event stream.
    
             The **device** portion of the event file name can be changed via the
             **-o** option.
    
           - blktrace may also be run concurrently with blkparse to produce
             **live** output -- to do this specify **-o -** for blktrace.
    
           - The default behaviour for blktrace is to run forever until
             explicitly killed by the user (via a control-C, or sending
             SIGINT signal to the process via invocation the kill (1)
             utility). Also you can specify a run-time duration for blktrace
             via the **-w** option -- then blktrace will run for the specified
             number of seconds, and then halt.
    


## OPTIONS



           -A _hex-mask_
           --set-mask=_hex-mask_
                  Set filter mask to _hex-mask_ (see below for masks)
    
           -a _mask_
           --act-mask=_mask_
                  Add _mask_ to current filter (see below for masks)
    
           -b _size_
           --buffer-size=_size_
                  Specifies buffer size for event extraction (scaled by
                  1024). The default buffer size is 512KiB.
    
           -d _dev_
           --dev=_dev_
                  Adds _dev_ as a device to trace
    
           -I _file_
           --input-devs=_file_
                  Adds the devices found in _file_ as devices to trace
    
           -n _num-sub_
           --num-sub-buffers=_num-sub_
                  Specifies number of buffers to use. blktrace defaults to 4
                  sub buffers.
    
           -l
           --listen
                  Run in network listen mode (blktrace server)
    
           -h _hostname_
           --host=_hostname_
                  Run in network client mode, connecting to the given host
    
           -p _number_
           --port=_number_
                  Network port to use (default 8462)
    
           -s
           --no-sendfile
                  Make the network client NOT use sendfile() to transfer data
    
           -o _basename_
           --output=_basename_
                  Specifies base name for input files. Default is
                  device.blktrace.cpu.  Specifying -o - runs in live mode
                  with blkparse (writing data to standard out).
    
           -D _dir_
           --output-dir=_dir_
                  Prepend _file_ to output file name(s)
    
                  This only works when supplying a single device, or when
                  piping the output via "-o -" with multiple devices.
    
           -r _rel-path_
           --relay=_rel-path_
                  Specifies debugfs mount point
    
           -v
           --version
                  Outputs version
    
           -V
           --version
                  Outputs version
    
           -w _seconds_
           --stopwatch=_seconds_
                  Sets run time to the number of seconds specified
    


## FILTER MASKS



           The following masks may be passed with the _-a_ command line option,
           multiple filters may be combined via multiple _-a_ command line
           options.
    
                  _barrier_ : barrier attribute
                  _complete_ : completed by driver
                  _discard_ : discard / trim traces
                  _fs_ : requests
                  _issue_ : issued to driver
                  _pc_ : packet command events
                  _queue_ : queue operations
                  _read_ : read traces
                  _requeue_ : requeue operations
                  _sync_ : synchronous attribute
                  _write_ : write traces
                  _notify_ : trace messages
                  _drv_data_ : additional driver specific trace
    


## REQUEST TYPES



           blktrace distinguishes between two types of block layer requests,
           file system and SCSI commands. The former are dubbed **fs** requests,
           the latter **pc** requests. File system requests are normal read/write
           operations, i.e.  any type of read or write from a specific disk
           location at a given size. These requests typically originate from
           a user process, but they may also be initiated by the vm flushing
           dirty data to disk or the file system syncing a super or journal
           block to disk. **pc** requests are SCSI commands. blktrace sends the
           command data block as a payload so that blkparse can decode it.
    


## EXAMPLES



           To trace the i/o on the device _/dev/sda_ and parse the output to
           human readable form, use the following command:
    
               % blktrace -d /dev/sda -o - | blkparse -i -
    
           This same behaviour can be achieve with the convenience script
           _btrace_.  The command
    
               % btrace /dev/sda
    
           has exactly the same effect as the previous command. See _btrace_
           (8) for more information.
    
           To trace the i/o on a device and save the output for later
           processing with _blkparse_ , use _blktrace_ like this:
    
               % blktrace /dev/sda /dev/sdb
    
           This will trace i/o on the devices _/dev/sda_ and _/dev/sdb_ and save
           the recorded information in the files _sda_ and _sdb_ in the current
           directory, for the two different devices, respectively.  This
           trace information can later be parsed by the _blkparse_ utility:
    
               % blkparse sda sdb
    
           which will output the previously recorded tracing information in
           human readable form to stdout.  See _blkparse_ (1) for more
           information.
    


* * *