iowatcher/README

   1 iowatcher graphs the results of a blktrace run.  It has a few different modes:
   2
   3         * Graph the result of an existing blktrace
   4
   5         * Start a new blktrace
   6
   7         * Start a new blktrace and a benchmark run
   8
   9         * Make a movie of the IO from a given trace (only mp4 for now)
  10
  11 Output:
  12
  13         iowatcher can produce either svg files or mp4 movies.  Most browsers
  14         can view the svg files, or you can use rsvg-view-3 from librsvg.
  15         rsvg-convert can turn the svgs into many other formats.
  16
  17 Building:
  18
  19         Type make and make install.  We need ffmpeg or png2theora, and
  20         librsvg to make movies, otherwise there are no dependencies.
  21
  22 The basic options:
  23
  24         -d controls which device you are tracing.  You can only trace one device
  25            at a time for now.  It is sent directly to blktrace, and only
  26            needed when you are making a new trace.
  27
  28         -t controls the name of the blktrace file.  iowatcher uses a dump from
  29            blkparse, so -t tries to guess the name of the corresponding
  30            per CPU blktrace data files if the dump file doesn't already exist.
  31
  32            If you want more than one trace in a given graph, you can specify
  33            -t more than once.
  34
  35         -F Add a fio bandwidth log graph.  You need to run fio --bandwidth-log
  36            to get one of these, and then pass either the read log or the write
  37            log into iowatcher.
  38
  39         -l Sets a label in the graph for a trace file.  The labels are added in
  40            the same order the trace files are added.
  41
  42         -m Create a movie.  The file format depends on the extension used in the
  43            -o filename.* option.  If you specify an .ogv or .ogg extension, the
  44            result will be Ogg Theora video, if png2theora is available.
  45            If you use an .mp4 extension, the result will be an mp4 video if
  46            ffmpeg is avilable.  You can use any other extension, but the end
  47            result will be an mp4.
  48
  49            You can use --movie=spindle or --movie=rect, which changes the
  50            style of the IO mapping.
  51
  52         -T Set a title for the graph.  This goes at the top of the image.
  53
  54         -o output filename.  The default is trace.svg.  iowatcher is
  55            only able to create svg for now.
  56
  57         -r control the duration in seconds for the rolling average.
  58            iowatcher tries to smooth out bumpy graphs by averaging the
  59            current second with seconds from the past.  Longer numbers here
  60            give you flatter graphs.
  61
  62         -P add per-process tags to the IO.  Each process responsible for
  63            submitting the IO gets a different color.
  64
  65         -O add a single graph to the output.  By default all the graphs
  66            are included, but with -O you get only the graphs you ask for.
  67            -O may be used more than once.
  68
  69         -N remove a single graph from the output.  This may also be used more
  70            than once.
  71
  72         Choices for -O and -N are:
  73            io, fio, tput, latency, queue_depth, iops, cpu-sys, cpu-io,
  74            cpu-irq, cpu-user, cpu-soft
  75
  76 Examples:
  77
  78         # generate graph from the existing trace.dump
  79         iowatcher -t trace.dump -o trace.svg
  80
  81         # skip the IO graph
  82         iowatcher -t trace.dump -o trace.svg -N io
  83
  84         # only graph tput and latency
  85         iowatcher -t trace.dump -o trace.svg -O tput -O latency
  86
  87         # generate a graph from two runs, and label them
  88         iowatcher -t ext4.dump -t xfs.dump -l Ext4 -l XFS -o trace.svg
  89
  90         # Run a fio benchmark and store the trace in trace.dump
  91         # add a title to the top.  Use /dev/sda for blktrace
  92         iowatcher -d /dev/sda -t trace.dump -T 'Fio Benchmark' -p 'fio some_job_file'
  93
  94         # Make a movie from an existing trace
  95         iowatcher -t trace --movie -o trace.mp4
  96
  97 Please email chris.mason@fusionio.com with any questions