# iowatcher

## NAME



           iowatcher - Create visualizations from blktrace results
    


## SYNOPSIS



           **iowatcher** _[options]_ [--] _[program arguments ...]_
    


## DESCRIPTION



           iowatcher graphs the results of a blktrace run.  It can graph the
           result of an existing blktrace, start a new blktrace, or start a
           new blktrace and a benchmark run.  It can then create an image or
           movie of the IO from a given trace.  iowatcher can produce either
           SVG files or movies in mp4 format (with ffmpeg) or ogg format
           (with png2theora).
    


## OPTIONS



           **--help** Print a brief usage summary.
    
           **-d, --device** _device_
                  Controls which device you are tracing.  You can only trace
                  one device at a time for now.  It is sent directly to
                  blktrace, and only needed when you are making a new trace.
    
           **-D, --blktrace-destination** _destination_
                  Destination for blktrace.
    
           **-p, --prog**
                  Run a program while blktrace is run. The program and its
                  arguments must be specified after all other options.  Note
                  that this option previously required the program to be
                  given as a single argument but it now tells **iowatcher** to
                  expect extra arguments which it should be run during the
                  trace.
    
           **--** End option parsing. If **--prog** is specified, everything
                  after **--** is the program to be run. This can be useful if
                  the program name could otherwise be mistaken for an option.
    
           **-K, --keep-movie-svgs**
                  Keep the SVG files generated for movie mode.
    
           **-t, --trace** _path_
                  Specify the name of the file or directory in which blktrace
                  output is located.  **iowatcher** uses a dump from blkparse, so
                  this option tries to guess the name of the corresponding
                  per-CPU blktrace data files if the dump file doesn't
                  already exist.  To add multiple traces to a given graph,
                  you can specify **--trace** more than once.  If _path_ is a
                  directory, **iowatcher** will use the name of the directory as
                  the base name of the dump file and all trace files found
                  inside the directory will be processed.
    
           **-l, --label** _label_
                  Sets a label in the graph for a trace file.  The labels are
                  added in the same order as the trace files.
    
           **-m, --movie** _[style]_
                  Create a movie.  The file format depends on the extension
                  used in the **-o** _file_ option.  If you specify an .ogv or .ogg
                  extension, the result will be Ogg Theora video, if
                  png2theora is available.  If you use an .mp4 extension, the
                  result will be an mp4 video if ffmpeg is available.  You
                  can use any other extension, but the end result will be an
                  mp4.  The accepted _style_ values are **spindle** for a circular
                  disc-like effect (default) or **rect** for a rectangular graph
                  style.
    
           **-T, --title** _title_
                  Set a _title_ to be placed at the top of the graph.
    
           **-o, --output** _file_
                  Output filename for the SVG image or video. The video
                  format used will depend on the file name extension. See
                  **--movie** for details.
    
           **-r, --rolling** _seconds_
                  Control the duration for the rolling average.  **iowatcher**
                  tries to smooth out bumpy graphs by averaging the current
                  second with seconds from the past.  Larger numbers here
                  give you flatter graphs.
    
           **-h, --height** _height_
                  Set the height of each graph
    
           **-w, --width** _width_
                  Set the width of each graph
    
           **-c, --columns** _columns_
                  Number of columns in graph output
    
           **-x, --xzoom** _min:max_
                  Limit processed time range to _min:max_.
    
           **-y, --yzoom** _min:max_
                  Limit processed sectors to _min:max_.
    
           **-a, --io-plot-action** _action_
                  Plot _action_ (one of Q, D, or C) in the IO graph.
    
           **-P, --per-process-io**
                  Distinguish between processes in the IO graph.
    
           **-O, --only-graph** _graph_
                  Add a single graph to the output (see section **GRAPHS** for
                  options).  By default all graphs are included. Use **-O** to
                  generate only the required graphs.  **-O** may be used more
                  than once.
    
           **-N, --no-graph** _type_
                  Remove a single graph from the output (see section **GRAPHS**
                  for options).  This option may be used more than once.
    


## GRAPHS



           Values accepted by the **-O** and **-N** options are:
    
              io, tput, latency, queue_depth, iops, cpu-sys, cpu-io, cpu-irq,
           cpu-user, cpu-soft
    


## EXAMPLES



           Generate graph from the existing trace.dump:
    
                  # iowatcher -t trace
    
           Skip the IO graph:
    
                  # iowatcher -t trace.dump -o trace.svg -N io
    
           Only graph tput and latency:
    
                  # iowatcher -t trace.dump -o trace.svg -O tput -O latency
    
           Generate a graph from two runs, and label them:
    
                  # iowatcher -t ext4.dump -t xfs.dump -l Ext4 -l XFS -o
                  trace.svg
    
           Run a fio benchmark and store the trace in trace.dump, add a title
           to the top, use /dev/sda for blktrace:
    
                  # iowatcher -d /dev/sda -t trace.dump -T 'Fio Benchmark' -p
                  fio some_job_file
    
           Make a movie from an existing trace:
    
                  # iowatcher -t trace --movie -o trace.mp4
    


* * *