doc/iowatcher.1

   1 .TH iowatcher "1" "April 2014" "iowatcher" "User Commands"
   2
   3 .SH NAME
   4 iowatcher - Create visualizations from blktrace results
   5
   6 .SH SYNOPSIS
   7 .B iowatcher
   8 \fI[options]\fR [--] \fI[program arguments ...]\fR
   9
  10 .SH DESCRIPTION
  11 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).
  12
  13 .SH OPTIONS
  14 .TP
  15 \fB--help\fP
  16 Print a brief usage summary.
  17 .TP
  18 \fB-d, --device\fP \fIdevice\fP
  19 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.
  20 .TP
  21 \fB-D, --blktrace-destination\fP \fIdestination\fP
  22 Destination for blktrace.
  23 .TP
  24 \fB-p, --prog\fP
  25 Run a program while blktrace is run. The program and its arguments must be
  26 specified after all other options.  Note that this option previously required
  27 the program to be given as a single argument but it now tells \fBiowatcher\fP
  28 to expect extra arguments which it should be run during the trace.
  29 .TP
  30 \fB--\fP
  31 End option parsing. If \fB--prog\fP is specified, everything after \fB--\fP is
  32 the program to be run. This can be useful if the program name could otherwise
  33 be mistaken for an option.
  34 .TP
  35 \fB-K, --keep-movie-svgs\fP
  36 Keep the SVG files generated for movie mode.
  37 .TP
  38 \fB-t, --trace\fP \fIpath\fP
  39 Specify the name of the file or directory in which blktrace output is located.
  40 \fBiowatcher\fP uses a dump from blkparse, so this option tries to guess the
  41 name of the corresponding per-CPU blktrace data files if the dump file doesn't
  42 already exist.  To add multiple traces to a given graph, you can specify
  43 \fB--trace\fP more than once.  If \fIpath\fP is a directory, \fBiowatcher\fP
  44 will use the name of the directory as the base name of the dump file and all
  45 trace files found inside the directory will be processed.
  46 .TP
  47 \fB-l, --label\fP \fIlabel\fP
  48 Sets a label in the graph for a trace file.  The labels are added in the same order as the trace files.
  49 .TP
  50 \fB-m, --movie\fP \fI[style]\fP
  51 Create a movie.  The file format depends on the extension used in the \fB-o\fP
  52 \fIfile\fP option.  If you specify an .ogv or .ogg extension, the result will
  53 be Ogg Theora video, if png2theora is available.  If you use an .mp4 extension,
  54 the result will be an mp4 video if ffmpeg is available.  You can use any other
  55 extension, but the end result will be an mp4.  The accepted \fIstyle\fP values
  56 are \fBspindle\fP for a circular disc-like effect (default) or \fBrect\fP for a
  57 rectangular graph style.
  58 .TP
  59 \fB-T, --title\fP \fItitle\fP
  60 Set a \fItitle\fP to be placed at the top of the graph.
  61 .TP
  62 \fB-o, --output\fP \fIfile\fP
  63 Output filename for the SVG image or video. The video format used will depend
  64 on the file name extension. See \fB--movie\fP for details.
  65 .TP
  66 \fB-r, --rolling\fP \fIseconds\fP
  67 Control the duration for the rolling average.  \fBiowatcher\fP tries to smooth out bumpy graphs by averaging the current second with seconds from the past.  Larger numbers here give you flatter graphs.
  68 .TP
  69 \fB-h, --height\fP \fIheight\fP
  70 Set the height of each graph
  71 .TP
  72 \fB-w, --width\fP \fIwidth\fP
  73 Set the width of each graph
  74 .TP
  75 \fB-c, --columns\fP \fIcolumns\fP
  76 Number of columns in graph output
  77 .TP
  78 \fB-x, --xzoom\fP \fImin:max\fP
  79 Limit processed time range to \fImin:max\fP.
  80 .TP
  81 \fB-y, --yzoom\fP \fImin:max\fP
  82 Limit processed sectors to \fImin:max\fP.
  83 .TP
  84 \fB-a, --io-plot-action\fP \fIaction\fP
  85 Plot \fIaction\fP (one of Q, D, or C) in the IO graph.
  86 .TP
  87 \fB-P, --per-process-io\fP
  88 Distinguish between processes in the IO graph.
  89 .TP
  90 \fB-O, --only-graph\fP \fIgraph\fP
  91 Add a single graph to the output (see section \fBGRAPHS\fP for options).  By
  92 default all graphs are included. Use \fB-O\fP to generate only the required
  93 graphs.  \fB-O\fP may be used more than once.
  94 .TP
  95 \fB-N, --no-graph\fP \fItype\fP
  96 Remove a single graph from the output (see section \fBGRAPHS\fP for options).
  97 This option may be used more than once.
  98 .SH GRAPHS
  99 Values accepted by the \fB-O\fP and \fB-N\fP options are:
 100
 101    io, tput, latency, queue_depth, iops, cpu-sys, cpu-io, cpu-irq, cpu-user, cpu-soft
 102
 103 .SH EXAMPLES
 104 Generate graph from the existing trace.dump:
 105 .PP
 106 .RS
 107 # iowatcher -t trace
 108 .RE
 109 .PP
 110 Skip the IO graph:
 111 .PP
 112 .RS
 113 # iowatcher -t trace.dump -o trace.svg -N io
 114 .RE
 115 .PP
 116 Only graph tput and latency:
 117 .PP
 118 .RS
 119 # iowatcher -t trace.dump -o trace.svg -O tput -O latency
 120 .RE
 121 .PP
 122 Generate a graph from two runs, and label them:
 123 .PP
 124 .RS
 125 # iowatcher -t ext4.dump -t xfs.dump -l Ext4 -l XFS -o trace.svg
 126 .RE
 127 .PP
 128 Run a fio benchmark and store the trace in trace.dump, add a title to the top, use /dev/sda for blktrace:
 129 .PP
 130 .RS
 131 # iowatcher -d /dev/sda -t trace.dump -T 'Fio Benchmark' -p fio some_job_file
 132 .RE
 133 .PP
 134 Make a movie from an existing trace:
 135 .PP
 136 .RS
 137 # iowatcher -t trace --movie -o trace.mp4
 138 .RE
 139
 140 .SH AUTHORS
 141 iowatcher was created and is maintained by Chris Mason.
 142
 143 This man page was largely written by Andrew Price based on Chris's original README.
 144
 145 .SH COPYRIGHT
 146 This program is free software; you can redistribute it and/or modify it under
 147 the terms of the GNU General Public License v2 as published by the Free
 148 Software Foundation.
 149
 150 This program is distributed in the hope that it will be useful, but WITHOUT ANY
 151 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 152 PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 153
 154 You should have received a copy of the GNU General Public License along with
 155 this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
 156 Street, Fifth Floor, Boston, MA 02110-1301 USA
 157
 158 .SH "SEE ALSO"
 159 .BR blktrace (8),
 160 .BR blkparse (1),
 161 .BR fio (1),
 162 .BR mpstat (1)