# btreplay

## NAME



           btreplay - recreate IO loads recorded by blktrace
    


## SYNOPSIS



           **btreplay [**_options_ ] <_dev_...>
    


## DESCRIPTION



           The _btrecord_ and _btreplay_ tools provide the ability to record and
           replay IOs captured by the _blktrace_ utility. Attempts are made to
           maintain ordering, CPU mappings and time-separation of IOs.
    
           The _blktrace_ utility provides the ability to collect detailed
           traces from the kernel for each IO processed by the block IO
           layer. The traces provide a complete timeline for each IO
           processed, including detailed information concerning when an IO
           was first received by the block IO layer — indicating the device,
           CPU number, time stamp, IO direction, sector number and IO size
           (number of sectors). Using this information, one is able to **replay**
           the IO again on the same machine or another set up entirely.
    
           The basic operating work-flow to replay IOs would be something
           like:
    
           -
               Run _blktrace_ to collect traces. Here you specify the
               device or devices that you wish to trace and later replay IOs
             upon. Note:
               the only traces you are interested in are **QUEUE** requests —
               thus, to save system resources (including storage for traces),
             one could
               specify the _-a queue_ command line option to _blktrace_.
    
           -
               While _blktrace_ is running, you run the workload that you
               are interested in.
    
           -
               When the work load has completed, you stop the _blktrace_
               utility (thus saving all traces over the complete workload).
    
           -
               You extract the pertinent IO information from the traces saved
             by
               _blktrace_ using the _btrecord_ utility. This will parse
               each trace file created by _blktrace_ , and crafty IO
             descriptions
               to be used in the next phase of the workload processing.
    
           -
               Once _btrecord_ has successfully created a series of data
               files to be processed, you can run the _btreplay_ utility which
               attempts to generate the same IOs seen during the sample
             workload phase.
    


## OPTIONS



           -c <_num_ >
           --cpus=<_num_ >
                  Set number of CPUs to use.
    
           -d <_dir_ >
           --input-directory=<_dir_ >
                  Set input directory.  This option requires a single
                  parameter providing the directory name for where input
                  files are to be found. The default directory is the current
                  directory (_._).
    
           -F
           --find-records
                  Find record files automatically This option instructs
                  _btreplay_ to go find all the record files in the directory
                  specified (either via the _-d_ option, or in the default
                  directory (_._).
    
           -h
           --help
                  Show help and exit.
    
           -i <_basename_ >
           --input-base=<_basename_ >
                  Set base name for input files.  Each input file has 3
                  fields:
    
                  1.
                      Device identifier (taken directly from the device name
                     of the
                      _blktrace_ output file).
    
                  2.
                      _btrecord_ base name — by default ``replay''.
    
                  3.
                      The CPU number (again, taken directly from the
                      _blktrace_ output file name).
    
                  This option requires a single parameter that will override
                  the default name (replay), and replace it with the
                  specified value.
    
           -I <_num_ >
           --iterations=<_num_ >
                  Set number of iterations to run.  This option requires a
                  single parameter which specifies the number of times to run
                  through the input files. The default value is 1
    
           -M <_filename_ >
           --map-devs=<_filename_ >
                  Specify device mappings.  This option requires a single
                  parameter which specifies the name of a file contain device
                  mappings. The file must be very simply managed, with just
                  two pieces of data per line:
    
                  -
                      The device name on the recorded system (with the
                    '_/dev/_ '
                      removed). Example: _/dev/sda_ would just be _sda_.
    
                  -
                      The device name on the replay system to use (again,
                    without the
                      '_/dev/_ ' path prepended).
    
                  An example file for when one would map devices _/dev/sda_ and
                  _/dev/sdb_ on the recorded system to _dev/sdg_ and _sdh_ on the
                  replay system would be:
    
                         sda sdg
                         sdb sdh
    
                  The only entries in the file that are allowed are these two
                  element lines — we do not (yet?) support the notion of
                  blank lines, or comment lines, or the like.
    
                  The utility allows for multiple _-M_ options to be supplied
                  on the command line.
    
           -N
           --no-stalls
                  Disable pre-bunch stalls.  When specified on the command
                  line, all pre-bunch stall indicators will be ignored. IOs
                  will be replayed without inter-bunch delays.
    
           -x <_factor_ >
           --acc-factor=<_factor_ >
                  Specify acceleration factor. Default value is 1 (no
                  acceleration).
    
           -v
           --verbose
                  Enable verbose output.  When specified on the command line,
                  this option instructs _btreplay_ to store information
                  concerning each **stall** and IO operation performed by
                  _btreplay_. The name of each file so created will be the
                  input file name used with an extension of _.rep_ appended
                  onto it. Thus, an input file of the name _sdab.replay.3_
                  would generate a verbose output file with the name
                  _sdab.replay.3.rep_ in the directory specified for input
                  files.
    
                  In addition, _btreplay_ will also output to _stderr_ the names
                  of the input files being processed.
    
           -V
           --version
                  Show version number and exit.
    
           -W
           --write-enable
                  Enable writing during replay.  As a precautionary measure,
                  by default _btreplay_ will not process **write** requests. In
                  order to enable _btreplay_ to actually **write** to devices one
                  must explicitly specify the _-W_ option.
    


* * *