1iowatcher(1)                     User Commands                    iowatcher(1)
2
3
4

NAME

6       iowatcher - Create visualizations from blktrace results
7
8

SYNOPSIS

10       iowatcher [options] [--] [program arguments ...]
11
12

DESCRIPTION

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

OPTIONS

22       --help Print a brief usage summary.
23
24       -d, --device device
25              Controls  which  device you are tracing.  You can only trace one
26              device at a time for now.  It is sent directly to blktrace,  and
27              only needed when you are making a new trace.
28
29       -D, --blktrace-destination destination
30              Destination for blktrace.
31
32       -p, --prog
33              Run  a  program while blktrace is run. The program and its argu‐
34              ments must be specified after all other options.  Note that this
35              option  previously  required the program to be given as a single
36              argument but it now tells iowatcher to  expect  extra  arguments
37              which it should be run during the trace.
38
39       --     End  option parsing. If --prog is specified, everything after --
40              is the program to be run. This can be useful if the program name
41              could otherwise be mistaken for an option.
42
43       -K, --keep-movie-svgs
44              Keep the SVG files generated for movie mode.
45
46       -t, --trace path
47              Specify the name of the file or directory in which blktrace out‐
48              put is located.  iowatcher uses a dump from  blkparse,  so  this
49              option tries to guess the name of the corresponding per-CPU blk‐
50              trace data files if the dump file doesn't already exist.  To add
51              multiple  traces  to a given graph, you can specify --trace more
52              than once.  If path is a directory, iowatcher will use the  name
53              of the directory as the base name of the dump file and all trace
54              files found inside the directory will be processed.
55
56       -l, --label label
57              Sets a label in the graph for a  trace  file.   The  labels  are
58              added in the same order as the trace files.
59
60       -m, --movie [style]
61              Create  a  movie.  The file format depends on the extension used
62              in the -o file option.  If you specify an .ogv  or  .ogg  exten‐
63              sion,  the  result  will  be  Ogg Theora video, if png2theora is
64              available.  If you use an .mp4 extension, the result will be  an
65              mp4  video if ffmpeg is available.  You can use any other exten‐
66              sion, but the end result will be an  mp4.   The  accepted  style
67              values  are spindle for a circular disc-like effect (default) or
68              rect for a rectangular graph style.
69
70       -T, --title title
71              Set a title to be placed at the top of the graph.
72
73       -o, --output file
74              Output filename for the SVG image or  video.  The  video  format
75              used  will  depend  on  the file name extension. See --movie for
76              details.
77
78       -r, --rolling seconds
79              Control the duration for the rolling average.   iowatcher  tries
80              to  smooth out bumpy graphs by averaging the current second with
81              seconds from the past.  Larger numbers  here  give  you  flatter
82              graphs.
83
84       -h, --height height
85              Set the height of each graph
86
87       -w, --width width
88              Set the width of each graph
89
90       -c, --columns columns
91              Number of columns in graph output
92
93       -x, --xzoom min:max
94              Limit processed time range to min:max.
95
96       -y, --yzoom min:max
97              Limit processed sectors to min:max.
98
99       -a, --io-plot-action action
100              Plot action (one of Q, D, or C) in the IO graph.
101
102       -P, --per-process-io
103              Distinguish between processes in the IO graph.
104
105       -O, --only-graph graph
106              Add  a  single  graph  to  the  output  (see  section GRAPHS for
107              options).  By default all graphs are included. Use -O to  gener‐
108              ate only the required graphs.  -O may be used more than once.
109
110       -N, --no-graph type
111              Remove  a  single  graph from the output (see section GRAPHS for
112              options).  This option may be used more than once.
113

GRAPHS

115       Values accepted by the -O and -N options are:
116
117          io, tput, latency, queue_depth, iops, cpu-sys, cpu-io, cpu-irq, cpu-
118       user, cpu-soft
119
120

EXAMPLES

122       Generate graph from the existing trace.dump:
123
124              # iowatcher -t trace
125
126       Skip the IO graph:
127
128              # iowatcher -t trace.dump -o trace.svg -N io
129
130       Only graph tput and latency:
131
132              # iowatcher -t trace.dump -o trace.svg -O tput -O latency
133
134       Generate a graph from two runs, and label them:
135
136              # iowatcher -t ext4.dump -t xfs.dump -l Ext4 -l XFS -o trace.svg
137
138       Run  a  fio benchmark and store the trace in trace.dump, add a title to
139       the top, use /dev/sda for blktrace:
140
141              # iowatcher -d /dev/sda -t trace.dump -T 'Fio Benchmark' -p  fio
142              some_job_file
143
144       Make a movie from an existing trace:
145
146              # iowatcher -t trace --movie -o trace.mp4
147
148

AUTHORS

150       iowatcher was created and is maintained by Chris Mason.
151
152       This  man  page  was  largely  written by Andrew Price based on Chris's
153       original README.
154
155
157       This program is free software; you can redistribute it and/or modify it
158       under  the  terms  of the GNU General Public License v2 as published by
159       the Free Software Foundation.
160
161       This program is distributed in the hope that it  will  be  useful,  but
162       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER‐
163       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU  General
164       Public License for more details.
165
166       You should have received a copy of the GNU General Public License along
167       with this program; if not, write to the Free Software Foundation, Inc.,
168       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
169
170

SEE ALSO

172       blktrace(8), blkparse(1), fio(1), mpstat(1)
173
174
175
176iowatcher                         April 2014                      iowatcher(1)
Impressum