filetop(8)

💖 filetop(8) — the System Manager's Manual page, but make it cute 💖

okay bestie, so filetop lives in the System Manager's Manual section 8, and it's genuinely one of my faves. it's top, but for files. that's the whole vibe. 🎀

---

✨ NAME ✨

filetop — File reads and writes by filename and process. Top for files. 👑

---

🌸 SYNOPSIS 🌸

filetop [-h] [-a] [-C] [-r MAXROWS] [-s {reads,writes,rbytes,wbytes}]
[-p PID] [--read-only] [--write-only] [interval] [count]

---

🦋 DESCRIPTION 🦋

This is top for files. periodt.

It traces file reads and writes, and prints a per-file summary every interval (by default, 1 second). By default the summary is sorted on the highest read throughput (Kbytes). The sorting order can be changed via the -s option. By default only IO on regular files is shown. The -a option will list all file types (sockets, FIFOs, etc). Only read or only write operations can be traced using --read-only or --write-only options respectively. By default both are traced. Using both options at once will raise an Exception. 😭 (not me, the program. it's giving conflict energy.)

This uses in-kernel eBPF maps to store per process summaries for efficiency. slay.

This script works by tracing the __vfs_read() and __vfs_write() functions using kernel dynamic tracing, which instruments explicit read and write calls. If files are read or written using another means (eg, via mmap()), then they will not be visible using this tool. Also, this tool will need updating to match any code changes to those vfs functions. iykyk, kernel internals move, tools gotta move with them. 💅

This should be useful for file system workload characterization when analyzing the performance of applications.

Note that tracing VFS level reads and writes can be a frequent activity, and this tool can begin to cost measurable overhead at high I/O rates. 🫠

Since this uses BPF, only the root user can use this tool. no root, no vibes. ✋

---

🌈 REQUIREMENTS 🌈

CONFIG_BPF and bcc. that's it, that's the whole guest list. 💜

---

✨ OPTIONS ✨

• -a — Include non-regular file types (sockets, FIFOs, etc).
• -C — Don't clear the screen.
• -r MAXROWS — Maximum number of rows to print. Default is 20.
• -s {reads,writes,rbytes,wbytes} — Sort column. Default is rbytes (read throughput).
• -p PID — Trace this PID only.
• --read-only — Trace read operations only.
• --write-only — Trace write operations only.
• interval — Interval between updates, seconds.
• count — Number of interval summaries.

---

🎀 EXAMPLES 🎀

Summarize block device I/O by process, 1 second screen refresh:

# filetop

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

# filetop -Cr 8

5 second summaries, 10 times only:

# filetop 5 10

---

🌸 FIELDS 🌸

• loadavg: — The contents of /proc/loadavg
• PID — Process ID.
• COMM — Process name.
• READS — Count of reads during interval.
• WRITES — Count of writes during interval.
• R_Kb — Total read Kbytes during interval.
• W_Kb — Total write Kbytes during interval.
• T — Type of file: R == regular, S == socket, O == other (pipe, etc).
• FILE — Filename.

---

💀 OVERHEAD 💀

Depending on the frequency of application reads and writes, overhead can become significant, in the worst case slowing applications by over 50%. 😳 Hopefully for real world workloads the overhead is much less — test before use. The reason for the high overhead is that VFS reads and writes can be a frequent event, and despite the eBPF overhead being very small per event, if you multiply this small overhead by a million events per second, it becomes a million times worse. Literally. You can gauge the number of reads and writes using the vfsstat(8) tool, also from bcc.

fr fr, test this on a real workload before you point it at prod. 🙈

---

⭐ SOURCE ⭐

This is from bcc.

https://github.com/iovisor/bcc

Also look in the bcc distribution for a companion _examples.txt file containing example usage, output, and commentary for this tool.

---

🐧 OS 🐧

Linux

---

🧚 STABILITY 🧚

Unstable - in development. she's still growing, be nice to her. 🦋

---

👑 AUTHOR 👑

Brendan Gregg

---

💫 INSPIRATION 💫

top(1) by William LeFebvre

---

💅 SEE ALSO 💅

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

---

and that's the whole page bestie 🫶 — this one's from the USER COMMANDS corner of the manual, dated 2016-02-08, and it's filed under filetop(8). go watch some files, main character. ✨🍓