dirtop(8)

🎀 dirtop(8) 🎀

manual name: dirtop(8), the System Manager's Manual, so it's giving admin-tool energy 💅

✨ NAME ✨

dirtop - File reads and writes by directory. Top for directories. 🦋

🪄 SYNOPSIS 🪄

dirtop -d directory1,directory2,... [-h] [-C] [-r MAXROWS] [-s {reads,writes,rbytes,wbytes}] [-p PID] [interval] [count]

💖 DESCRIPTION 💖

okay so this is literally top for directories 😭✨

It traces file reads and writes and prints a per-directory summary every interval (by default, 1 second). By default the summary is sorted on the highest read throughput (Kbytes), but you can change the sorting order with the -s option. main character energy 👑

It uses in-kernel eBPF maps to store per-process summaries, so it's efficient. the way that 🧚

This script works by tracing the __vfs_read() and __vfs_write() functions with kernel dynamic tracing, which instruments explicit read and write calls. ngl, if files get read or written some other way (eg, via mmap()), they will not show up here 🙈 Also, this tool will need updating to match any code changes to those VFS functions.

This should be super useful for file system workload characterization when you're analyzing how applications perform 🍓

Heads up bestie: tracing VFS level reads and writes can happen a LOT, so this tool can start costing measurable overhead at high I/O rates 💀

Since this uses BPF, only the root user can use this tool 🔥

🧰 REQUIREMENTS 🧰

CONFIG_BPF and bcc. iykyk 💜

🎛️ OPTIONS 🎛️

• -d — give it a comma-separated list of directories to watch. Wildcards work if they're between single brackets 🌸
• -C — don't clear the screen between updates 🫶
• -r MAXROWS — the max number of rows to print. Default is 20 ✨
• -s {reads,writes,rbytes,wbytes} — pick the sort column. Default is rbytes (read throughput) 🔥
• -p PID — only trace this PID, bestie 🎯
• interval — how long between updates, in seconds ⏰
• count — how many interval summaries you want before it stops 🛑

📸 EXAMPLES 📸

Summarize block device I/O by directory, with a 1 second screen refresh:

# dirtop -d '/hdfs/uuid/*/yarn'

Don't clear the screen, and only show the top 8 rows:

# dirtop -d '/hdfs/uuid/*/yarn' -Cr 8

5 second summaries, 10 times only:

# dirtop -d '/hdfs/uuid/*/yarn' 5 10

Report read & write IOs generated across multiple yarn and data directories:

# dirtop -d '/hdfs/uuid/*/yarn,/hdfs/uuid/*/data'

🏷️ FIELDS 🏷️

• loadavg: — the contents of /proc/loadavg 📈
• READS — count of reads during the interval 📖
• WRITES — count of writes during the interval ✍️
• R_Kb — total read Kbytes during the interval 💧
• W_Kb — total write Kbytes during the interval 🌊
• PATH — the path where the IOs were accounted 🗂️

💸 OVERHEAD 💸

okay real talk, depending on how often the app does reads and writes, the overhead can get significant. In the worst case it can slow applications down by over 50% 😭 Hopefully real-world workloads see way less, but test before you use it. The reason it's so heavy is that VFS reads and writes can be super frequent. Even though the eBPF overhead per event is tiny, multiply that by a million events per second and it becomes a million times worse. Literally. 💀 You can gauge how many reads and writes are happening with the vfsstat(8) tool, also from bcc.

🌐 SOURCE 🌐

This is from bcc:

https://github.com/iovisor/bcc

Also check the bcc distribution for a companion _examples.txt file with example usage, output, and commentary for this tool 📚

🐧 OS 🐧

Linux 💜

🚧 STABILITY 🚧

Unstable, it's still in development 🛠️

👩‍💻 AUTHOR 👩‍💻

Erwan Velu 🫶

💡 INSPIRATION 💡

filetop(8) by Brendan Gregg, the OG 👑

🔗 SEE ALSO 🔗

vfsstat(8), vfscount(8), fileslower(8) 🦋

---

🌈 Filed under user commands, last updated 2020-03-16. Source is bcc, so go check it out, and be safe with that overhead, bestie 💅🎀