topline(1)

🎀 topline — a disk/per-core CPU grapher/logger 💖

okay bestie, gather round, because topline is genuinely that girl. it graphs your disks AND your per-core CPU, live, and it does it in a way that actually fits on your screen. the manual page calls this thing topline(1) from the General Commands Manual, and honestly? iconic.

---

✨ SYNOPSIS ✨

topline [ -l ] [ -i 1.0 ] [ -o logfile ] [ program arg1 arg2 ...  ]

that's it. that's the whole vibe. 🫶

---

🌸 DESCRIPTION 🌸

so like, here's the situation. tools like htop can totally show you per-core loads, but they do it interactively — you gotta sit there and stare. and then there's loggers like dstat, but they're working with numeric data, so they have zero chance of fitting per-CPU info inside a single line on a modern many-core processor. it's giving crowded. it's giving 128 cores and one sad terminal. 😭

so topline said "not me" and decided to use Unicode graphing symbols to squash all that data into a terse form — two hyperthreads per character, no cap. which means you can actually eyeball NUMA separation, CPU hopping, etc. main character energy fr fr. 👑

Once per second, topline plots stats for that interval:

• per every disk — one character with two columns of dots gives that disk's utilization time percentage. the left column shows reads, the right one shows writes. disks are grouped into parenthesised groups by interface type (NVMe, SATA, eMMC, ...).
• per every non-hyperthreaded CPU or a pair of hyperthreaded siblings — a character with one or two columns is given. non-HT CPUs are drawn with bars, HT ones with dots, offline cores are marked with 'o'. the parentheses group CPUs by their NUMA node.

---

💅 OPTIONS 💅

• <program> <arg1> <arg2> ... — runs a program and terminates the graph once the program exits. heads up though: the graph still exhibits the global state of the system rather than just the program you chose and its children. so it's not a spotlight, it's the whole group photo. 📸

If no program is given, topline will keep logging forever (ie, until you press ^C or similar). forever-ever. 🦋

• -l, --line-output, --linearize — marshalls the program's output line-by-line, avoiding mix-ups with topline's data. they will be interspersed in separate lines. the program will know it is being piped; if you want it to believe it's ran on a terminal (to get colors, etc) you may use a tool like pipetty. sneaky little makeover, love that for it. 💄
• -i <interval> — sets the interval between data samples; the default is 1s. floating-point values are allowed; the number may be suffixed by a "s" (seconds, default), "m" (minutes), "h" (hours), "d" (days), "ms" (milliseconds), "us" or "µs" (microseconds). so go off, pick your own tempo. ⏱️
• -o <file>, --output <file> — redirects topline's output to the given file. the program being ran can then use stdout and stderr unimpeded. everybody gets their own lane. 🛣️
• -d, --dump-after, --delay-dump — suppresses the graph output until after the program exits, then dumps the logged graph all at once to stderr. good for non-interactive builds. NB. ^C assumes you want to abort both the program and topline, please kill the former some other way if that is not the case. read that twice, bestie. 👀

---

⚠️ CAVEATS ⚠️

bestie. bestie. listen. these are the "read before you @ me" notes.

• If the machine's CPUs are hyperthreaded with more than one or two per core, the graph won't make it obvious which columns share a core. all siblings are still given consecutively, unless forced into separate NUMA nodes with fakenuma settings.
• Machines above circa 140 CPUs may not fit on an 80-column terminal. that's a lot of core. she's doing her best. 🥲
• All utilization figures are global to the machine even if caused by something else than the program you run.

---

🔍 SEE ALSO 🔍

htop, dstat, VTUNE.

go read those too, they're the friend group. 🌈

---

and that's the whole page, babe 💖 this one's from the General Commands Manual, dated 2019-12-29, and it's topline(1) — so go graph something pretty. slay, log, and hydrate. ✨🫶