statsnoop.bt(8)

📦
version 0.27.0 · 4 versions
, in alpine 3.24, arch rolling, centos-stream 10, centos-stream 9, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💅 statsnoop.bt — bestie's guide to stalking your stat() syscalls

okay so. this is a page from the System Manager's Manual, section 8, and the tool is called statsnoop.bt. it's giving detective energy, but for syscalls. let's get into it 💖

✨ NAME ✨

statsnoop.bt — trace stat() syscalls. no cap, that's the whole vibe. it runs on bpftrace/eBPF.

🌸 SYNOPSIS 🌸

statsnoop.bt

that's it. that's the whole command. no flags, no arguments, just pure main character energy 🫶

🦋 DESCRIPTION 🦋

okay so statsnoop traces the stat() syscall, and it shows you which processes are trying to stat which files. literally a receipts printer for file-lookups 💅

why do you care? because this is lowkey the cheat code for:

  • figuring out where your config and log files actually live
  • troubleshooting apps that are failing, especially on startup (ngl startup failures are the WORST, they just ✨vanish✨)

so here's the tea: this tool traces the tracepoints for statfs(), statx(), newstat(), and newlstat(). but bestie, listen — those are not the only stat syscalls out there. so if you're missing activity, you might need to add more variants yourself. iykyk 😭

and the biggest caveat of all: since this uses BPF, only the root user can use this tool. root only. periodt. 👑

🎀 REQUIREMENTS 🎀

  • CONFIG_BPF
  • bcc

that's the whole list. if you have those, you're slaying ✨

🔥 EXAMPLES 🔥

trace all the stat() syscalls, every single one:

# statsnoop.bt

ate. no notes. 💖

🌈 FIELDS 🌈

here's what each column is serving:

  • PID — Process ID. who's doing it.
  • COMM — Process name. the name of who's doing it.
  • ERR — Error number (go check the system's errno.h for what each one means)
  • PATH — Stat path. the file they were trying to peek at 👀

⭐ OVERHEAD ⭐

okay so this traces the stat tracepoints and prints output for each event. and the way that this is generally expected to be low-rate (< 1000/s), the overhead is also expected to be negligible. so you're fine, probably 🫶

BUT — if you have an application that's calling a high rate of stat()s, then please, for the love of everything, test and understand overhead before use. do not just yolo it. 🙈

💜 SOURCE 💜

this is from bpftrace.

https://github.com/bpftrace/bpftrace

also! look in the bpftrace distribution for a companion _examples.txt file — it's got example usage, output, and commentary for this tool. it's the director's commentary track, basically 🎬

and for the lore: this is a bpftrace version of the bcc tool of the same name. the bcc tool may provide more options and customizations, so if you want extra toppings, go look there:

https://github.com/iovisor/bcc

🧚 OS 🧚

Linux 🐧 (obviously bestie)

💀 STABILITY 💀

Unstable — in development.

translation: it works, but it's still growing. be gentle. it's in its development arc 🌱

👑 AUTHOR 👑

Brendan Gregg

(the icon. the legend. we stan.) 💖

🌸 SEE ALSO 🌸

and that's the whole page, bestie!! this one came out of the USER COMMANDS section, dated 2018-09-08, and it's filed under statsnoop.bt(8). go trace some syscalls and slay 💅✨🦋

📦 where this page comes from