cachestat(8)

💖 cachestat(8) — the page cache vibe check 💖

Okay bestie, so this is cachestat, from the Linux System Manager's Manual. It's a little eBPF/bcc tool that tells you how your Linux page cache is doing — hits, misses, the whole situation. Think of it as a wellness check for your memory, and you're the one holding the clipboard. 🎀

---

✨ NAME ✨

cachestat — statistics for linux page cache hit/miss ratios. Uses Linux eBPF/bcc. That's the whole identity, no cap.

---

🌸 SYNOPSIS 🌸

cachestat [-T] [interval [count]]

Short, sweet, iconique.

---

💅 DESCRIPTION 💅

So what it actually does: it traces four kernel functions and prints per-second summaries. Very demure, very mindful. It's genuinely useful for general workload characterization, and for spotting patterns in operation usage over time. Like, what is your system actually doing all day? This tells you. 🔥

How does it do it? By tracing kernel page cache functions using dynamic tracing — which is the important bit — and it will need updating to match any changes to these functions. So if the kernel moves, the script breaks, and you're the one fixing it. Edit the script to customize which functions are traced. You have the power. 👑

And because this uses BPF, only the root user can use this tool. Sorry to the non-root girlies, this one's not for you. 😭

---

🧚 REQUIREMENTS 🧚

• CONFIG_BPF
• bcc

Both of them. Non-negotiable, bestie.

---

🦋 EXAMPLES 🦋

Print summaries every second:

# cachestat

Print summaries every second with timestamp:

# cachestat -T

Print output every five seconds, three times:

# cachestat 5 3

Print output with timestamp every five seconds, three times:

# cachestat -T 5 3

See the pattern? It's giving learn the flags once, use them forever. 💜

---

⭐ FIELDS ⭐

This is the part where you learn what all the little words mean. Pay attention, this is the good part. 🍓

• TIME — Timestamp. Literally just what time it is.
• HITS — Number of page cache hits. The wins. 🌈
• MISSES — Number of page cache misses. The L's. 💀
• DIRTIES — Number of dirty pages added to the page cache.
• HITRATIO — The hit ratio as a percentage. The main character number, honestly.
• READ_HIT% — Read hit percent of page cache usage.
• WRITE_HIT% — Write hit percent of page cache usage.
• BUFFERS_MB — Buffers size taken from /proc/meminfo.
• CACHED_MB — Cached amount of data in current page cache taken from /proc/meminfo.

---

🔥 OVERHEAD 🔥

Okay so, real talk. This traces various kernel page cache functions and maintains in-kernel counts, which are asynchronously copied to user-space. While the rate of operations can be very high (>1G/sec), we can have up to 34% overhead. Bestie. 34%. That's a lot of overhead. 😭

But — it's still a relatively efficient way to trace these events, and so the overhead is expected to be small for normal workloads. Key words: normal workloads. Measure in a test environment. Please. For me. 🙈

---

🫶 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. It's like bonus content, and we love bonus content. ✨

---

💖 OS 💖

Linux. Obviously. 💅

---

👑 STABILITY 👑

Unstable — in development. She's still growing, she's still figuring herself out, and honestly? Same. 🦋

---

🌸 AUTHOR 🌸

Allan McAleavy — the icon who made this happen. Respect. 🫡

---

🎀 SEE ALSO 🎀

https://github.com/brendangregg/perf-tools/blob/master/fs/cachestat

---

Heads up bestie: this is a USER COMMANDS page from 2016-01-30, so if something looks ancient, that's because it is. Still slays though. 💜

That's the whole page, periodt. Go forth and check your cache. 💅✨