statsnoop.bt(8)

📦 version 0.17.0, in debian bookworm

✨ statsnoop.bt — the manual page but make it cute ✨

okay bestie, welcome to statsnoop.bt 💖 this is a page from section 8 of the system manager's manual, and it's literally about tracing stat() syscalls with bpftrace/eBPF. let's get into it 🫶

🌸 NAME 🌸

statsnoop.bt — trace stat() syscalls. uses bpftrace/eBPF. periodt.

🎀 SYNOPSIS 🎀

statsnoop.bt

that's it. no flags, no arguments, she just goes. main character energy fr 💅

🦋 DESCRIPTION 🦋

so statsnoop traces the stat() syscall, and it shows you which processes are attempting to stat which files. lowkey iconic. why do you care? because it's genuinely useful for figuring out where your config and log files live, and for troubleshooting apps that are failing — especially when they fail on startup 😭 like, that one file it can't find? this tool will tell you.

it traces the tracepoints for statfs(), statx(), newstat(), and newlstat(). ngl, these are not the only stat syscalls — so if you're missing activity, you may need to add more variants yourself. the tool is not gonna gaslight you about it, but she also can't do everything 💀

and since this uses BPF, only the root user can use this tool. no root, no stats. that's the vibe check and you failed it 🙈

💜 REQUIREMENTS 💜

  • CONFIG_BPF
  • bcc

both. or she's not running. simple as that 🎀

✨ EXAMPLES ✨

trace all the stat() syscalls:

# statsnoop.bt

ate. no crumbs. 🔥

🌈 FIELDS 🌈

here's what every line of output is giving:

  • PID — process ID
  • TID — thread ID
  • COMM — process name
  • FD — file descriptor (if it succeeded), or -1 (if it failed) 😭
  • ERR — error number (go look at your system's errno.h bestie)
  • PATH — the stat path

🔥 OVERHEAD 🔥

she traces the stat tracepoints and prints output for each event. and because the rate of this is generally expected to be low — like, < 1000/s low — the overhead is also expected to be negligible. ✨

but if you have an application that's calling a high rate of stat()s? then test and understand the overhead before use. do not just rawdog it. please. 🫶

🧚 SOURCE 🧚

this is from bpftrace.

https://github.com/iovisor/bpftrace

also, look in the bpftrace distribution for a companion _examples.txt file — it's got example usage, output, and commentary for this tool. so much lore in there 💖

this is a bpftrace version of the bcc tool of the same name. and heads up: the bcc tool may provide more options and customizations. so if you need more, she's right there.

https://github.com/iovisor/bcc

🍓 OS 🍓

Linux 🐧 (obviously)

💀 STABILITY 💀

Unstable — in development.

so like. she's growing. she's evolving. be nice to her 🙈

👑 AUTHOR 👑

Brendan Gregg

the icon, the legend, the moment ⭐

🫶 SEE ALSO 🫶

go read those next, bestie, they're the friend group 💜

and that's the whole page!! from the USER COMMANDS corner of the manual, dated 2018-09-08, this was statsnoop.bt(8) 🎀 mwah, go trace something pretty 💅✨

📦 where this page comes from