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

AUTHORS

       iowatcher was created and is maintained by Chris Mason.

       This man page was largely written by Andrew Price based on Chris's original README.

COPYRIGHT

       This program is free software; you can redistribute it and/or modify  it  under  the  terms  of  the  GNU
       General Public License v2 as published by the Free Software Foundation.

       This  program  is  distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
       the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General  Public
       License for more details.

       You  should have received a copy of the GNU General Public License along with this program; if not, write
       to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

SEE ALSO

       blktrace(8), blkparse(1), fio(1), mpstat(1)