cachestat(8)

💖 cachestat — the manual page, but make it cute 💖

okay bestie, welcome to cachestat, section 8 of the System Manager's Manual (yes, the System Manager's Manual, we're fancy like that). It measures page cache hits/misses, and it runs on Linux ftrace. Let's get into it 🦋

---

✨ NAME ✨

cachestat — measure page cache hits/misses. Uses Linux ftrace.

---

🌸 SYNOPSIS 🌸

cachestat [-Dht] [interval]

---

🎀 DESCRIPTION 🎀

So basically this tool gives you the basic cache hit/miss statistics for the Linux page cache. That's the whole vibe. 💅

The way it works right now is it uses Linux ftrace dynamic function profiling to build custom in-kernel counters, which is honestly a workaround until the kernel can just have counters like that built-in. And specifically, bestie, it counts four kernel functions:

• mark_page_accessed() — for measuring cache accesses
• mark_buffer_dirty() — for measuring cache writes
• add_to_page_cache_lru() — for measuring page additions
• account_page_dirtied() — for measuring page dirties

😭 okay so heads up: it is possible that these functions have been renamed (or are different logically) for your kernel version, and if that happens, this script will not work as-is. It was written for a Linux 3.13 kernel, and tested on a few other versions. This script is a sandcastle: the kernel may wash some away, and you'll need to rebuild. 🌊🏰

This program's implementation can be improved in the future when other kernel capabilities are made available. If you need a more reliable tool now, then consider other tracing alternatives (eg, SystemTap). Real talk: this tool is really a proof of concept to see what ftrace can currently do. 🔥

⚠️ WARNING: This uses dynamic tracing of kernel functions, and could cause kernel panics or freezes. Test, and know what you are doing, before use. It also traces cache activity, which can be frequent, and cost some overhead. The statistics should be treated as best-effort: there may be some error margin depending on unusual workload types. 😭

Since this uses ftrace, only the root user can use this tool. 👑

---

💜 REQUIREMENTS 💜

CONFIG_FUNCTION_PROFILER, which you may already have enabled and available on recent kernels, and awk. That's it, that's the list ✨

---

✨ OPTIONS ✨

• -D — Include extra fields for debug purposes (see script). 🐛
• -h — Print usage message. 🫶
• -t — Include timestamps in units of seconds. ⏰
• interval — Output interval in seconds. Default is 1.

---

🌈 EXAMPLES 🌈

Show per-second page cache statistics:

# cachestat

iconic, no notes 💅

---

🦋 FIELDS 🦋

• TIME — Time, in HH:MM:SS.
• HITS — Number of page cache hits (reads). Each hit is for one memory page (the size depends on your processor architecture; commonly 4 Kbytes). Since this tool outputs at a timed interval, this field indicates the cache hit rate.
• MISSES — Number of page cache misses (reads from storage I/O). Each miss is for one memory page. Cache misses should be causing disk I/O. Run iostat(1) for correlation (although the miss count and size by the time disk I/O is issued can differ due to I/O subsystem merging).
• DIRTIES — Number of times a page in the page cache was written to and thus "dirtied". The same page may be counted multiple times per interval, if it is written to multiple times. This field gives an indication of how much cache churn there is, caused by applications writing data.
• RATIO — The ratio of cache hits to total cache accesses (hits + misses), as a percentage.
• BUFFERS_MB — Size of the buffer cache, for disk I/O. From /proc/meminfo.
• CACHED_MB — Size of the page cache, for file system I/O. From /proc/meminfo.

---

⚡ OVERHEAD ⚡

This tool currently uses ftrace function profiling, which provides efficient in-kernel counters. However, the functions profiled are executed frequently, so the overheads can add up. Test and measure before use. My own testing showed around a 2% loss in application performance while this tool was running. 😮💨

---

💖 SOURCE 💖

This is from the perf-tools collection.

https://github.com/brendangregg/perf-tools

Also look under the examples directory for a text file containing example usage, output, and commentary for this tool. 📂

---

🌸 OS 🌸

Linux 🐧

---

🎀 STABILITY 🎀

Unstable — in development. (she's still growing, bestie) 🌱

---

👑 AUTHOR 👑

Brendan Gregg

---

🫶 SEE ALSO 🫶

iostat(1), iosnoop(8)

---

and that's the whole page, periodt 💅 This one came out of the USER COMMANDS corner of the manual, dated 2014-12-28, filed under cachestat(8) — go forth and measure those hits and misses, bestie, you've got this 🌈✨