iowatcher(1)

💅 iowatcher(1) — like, the User Commands one, bestie

Okay so picture this: you've got a blktrace run and a whole bunch of numbers, and honestly? Numbers are boring. iowatcher is the icon that turns all of that into visualizations — graphs, images, whole entire movies. It's giving data glow-up. ✨

It lives in the User Commands section of the manual, and the whole vibe is "make the IO make sense at a glance."

🌸 SYNOPSIS 🌸

iowatcher [options] [--] [program arguments ...]

🦋 DESCRIPTION 🦋

iowatcher graphs the results of a blktrace run. That's the whole assignment, and it ate. 💅

It's lowkey flexible too — it can:

• graph the result of an existing blktrace,
• start a new blktrace,
• or start a new blktrace and a benchmark run at the same time (main character energy, honestly).

Then it can create an image or a movie of the IO from a given trace. And the output format? iowatcher can produce either SVG files, or movies in mp4 format (with ffmpeg) or ogg format (with png2theora). Pick your fighter. 🎀

---

👑 OPTIONS 👑

• --help — prints a brief usage summary. Short, sweet, helpful. We love a king who gets to the point. 🫶
• -d, --device device — controls which device you are tracing. Heads up: you can only trace one device at a time for now. This gets sent directly to blktrace, and it's only needed when you're making a new trace.
• -D, --blktrace-destination destination — the destination for blktrace. That's it, that's the whole thing.
• -p, --prog — run a program while blktrace is run. The program and its arguments must be specified after all other options. And ngl, this one has lore: the option previously required the program to be given as a single argument, but now it tells iowatcher to expect extra arguments that it should run during the trace. Glow-up arc complete. 💖
• -- — end option parsing. If --prog is specified, everything after -- is the program to be run. Super useful when the program name could otherwise be mistaken for an option. Not me protecting your filenames from being misread as flags 😭
• -K, --keep-movie-svgs — keep the SVG files generated for movie mode. Hoarder behavior, but make it intentional. 🎀
• -t, --trace path — specifies 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.

Wanna add multiple traces to a given graph? Just specify --trace more than once. And 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. She's thorough. 👑

• -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 — so keep your pairs matched, bestie, order matters fr fr.
• -m, --movie [style] — create a movie. The file format depends on the extension used in the -o file option:
  • .ogv or .ogg extension → Ogg Theora video, if png2theora is available.
  • .mp4 extension → an mp4 video, if ffmpeg is available.
  • Any other extension → you can use it, 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. Spindle is the moment, rect is the minimalism. Choose wisely. 🌀

• -T, --title title — set a title to be placed at the top of the graph. Name your child. ✨
• -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 — controls 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. Basically a smoothing filter but make it self-care. 💆
• -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. Every process gets to be its own little star. ⭐
• -O, --only-graph graph — add a single graph to the output (see the GRAPHS section for your options). By default all graphs are included, so 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 (again, see GRAPHS). This option may be used more than once.

---

🌈 GRAPHS 🌈

The 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

Ten little icons, all valid, all valid. 💜

---

🍓 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. Founder energy. 👑

This man page was largely written by Andrew Price, based on Chris's original README. Credit where credit is due, always. 🫶

💀 COPYRIGHT 💀

Okay so this part is the legal bit and we do not paraphrase legal bits, so here it is in full:

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

No cap, read the license, it's important. 😭

💖 SEE ALSO 💖

blktrace(8), blkparse(1), fio(1), mpstat(1) — go read your friends, they're iconic too.

---

And that's the whole page, bestie! 🎀 Sending you off with the official sign-off: this is iowatcher from April 2014, filed under iowatcher(1) — same name at the top, same name at the bottom, symmetric queen. 💅✨