1iowatcher(1) User Commands iowatcher(1)
2
6 iowatcher - Create visualizations from blktrace results
7
10 iowatcher [options] [--] [program arguments ...]
11
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
22 --help Print a brief usage summary.
23 -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 -D, --blktrace-destination destination
30 Destination for blktrace.
31 -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 -- 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 -K, --keep-movie-svgs
44 Keep the SVG files generated for movie mode.
45 -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 -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 -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 -T, --title title
71 Set a title to be placed at the top of the graph.
72 -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 -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 -h, --height height
85 Set the height of each graph
86 -w, --width width
88 Set the width of each graph
89 -c, --columns columns
91 Number of columns in graph output
92 -x, --xzoom min:max
94 Limit processed time range to min:max.
95 -y, --yzoom min:max
97 Limit processed sectors to min:max.
98 -a, --io-plot-action action
100 Plot action (one of Q, D, or C) in the IO graph.
101 -P, --per-process-io
103 Distinguish between processes in the IO graph.
104 -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 -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
115 Values accepted by the -O and -N options are:
116 io, tput, latency, queue_depth, iops, cpu-sys, cpu-io, cpu-irq, cpu-
118 user, cpu-soft
119
122 Generate graph from the existing trace.dump:
123 # iowatcher -t trace
125 Skip the IO graph:
127 # iowatcher -t trace.dump -o trace.svg -N io
129 Only graph tput and latency:
131 # iowatcher -t trace.dump -o trace.svg -O tput -O latency
133 Generate a graph from two runs, and label them:
135 # iowatcher -t ext4.dump -t xfs.dump -l Ext4 -l XFS -o trace.svg
137 Run a fio benchmark and store the trace in trace.dump, add a title to
139 the top, use /dev/sda for blktrace:
140 # iowatcher -d /dev/sda -t trace.dump -T 'Fio Benchmark' -p fio
142 some_job_file
143 Make a movie from an existing trace:
145 # iowatcher -t trace --movie -o trace.mp4
147
150 iowatcher was created and is maintained by Chris Mason.
151 This man page was largely written by Andrew Price based on Chris's
153 original README.
154
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 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 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
172 blktrace(8), blkparse(1), fio(1), mpstat(1)
173iowatcher April 2014 iowatcher(1)