{"id":1499,"date":"2026-10-24T22:32:48","date_gmt":"2026-10-24T22:32:48","guid":{"rendered":"https:\/\/virtualserversvps.com\/blog\/?p=1499"},"modified":"2026-10-24T22:32:48","modified_gmt":"2026-10-24T22:32:48","slug":"measuring-page-cache-hit-ratio-vmtouch-cachestat","status":"publish","type":"post","link":"https:\/\/virtualserversvps.com\/blog\/measuring-page-cache-hit-ratio-vmtouch-cachestat\/","title":{"rendered":"Measuring Page-Cache Hit Ratio on a VPS with vmtouch and cachestat"},"content":{"rendered":"

free -h<\/code> showed 412 MB of 3.8 GB “available” on a web node also holding 610 MB of page cache for static assets \u2014 and could not say whether that cache was helping. Two tools answer it: vmtouch<\/code> for which files are resident, cachestat<\/code> for what fraction of reads the page cache serves. Together they turn a memory graph into a hit ratio with a target.<\/p>\n\n

This walkthrough uses Debian 12, kernel 6.1, and a 3.8 GB VPS<\/a> serving nginx from a 2.1 GB asset tree. Everything below is a command you can run on a live box without restarting anything.<\/p>\n\n

Why \/proc\/meminfo cannot give you a hit ratio<\/h2>\n\n

MemAvailable<\/code>, Cached<\/code> and Buffers<\/code> are instantaneous snapshots, not rates. Cached<\/code> rising tells you the cache is growing, not whether it is serving reads. The kernel does expose aggregate counters in \/proc\/vmstat<\/code> \u2014 pgpgin<\/code>, pgpgout<\/code>, pgmajfault<\/code> \u2014 but they are cumulative since boot and mix file-backed and anonymous pages, which makes rate computation awkward and misleading.<\/p>\n\n

grep -E \"pgpgin|pgmajfault|nr_file_pages\" \/proc\/vmstat\nfree -m\n# MemAvailable is an estimate; it cannot say which files are cached<\/code><\/pre>\n\n
A page-cache hit costs roughly 100 ns of copy; a miss costs an 80 \u00b5s NVMe read. At 20,000 file reads per second a 10% shift in hit ratio means 2,000 extra device reads per second \u2014 idle disk versus saturated.<\/p>\n\n
cachestat: hit ratio as a rate<\/h2>\n\n
cachestat<\/code> ships with bcc-tools and reads the kernel’s per-CPU cachestat counters in rate form. It prints hits\/misses\/dirty per one-second window; the ratio is hits\/(hits+misses).<\/p>\n\n
# apt install bcc-tools  (or bpfcc-tools on Debian)\ncachestat 1\n\n# example output\n#     HITS   MISSES  DIRTIES  HITRATIO   BUFFERS_MB  CACHED_MB\n#   142030     3120     1801    97.8%          192      3184\n#   138911     4102     2043    97.1%          192      3211<\/code><\/pre>\n\n
A cold cache after echo 3 > \/proc\/sys\/vm\/drop_caches<\/code> started at 21.4% and settled at 97.6\u201398.2%. The interesting figure is the 34 seconds to reach 95% \u2014 how long a reloaded worker serves slower responses. Never drop caches on production to “test performance”: it is a self-inflicted latency incident with a measurable duration.<\/p>\n\n
Run it under real traffic: on an idle box the ratio is dominated by systemd and cron reads. A useful run is 60 seconds at normal request rate, compared between configurations rather than trusted absolutely.<\/p>\n\n
vmtouch: which files are resident, and how much RAM they need<\/h2>\n\n
vmtouch<\/code> queries the page cache directly via mincore(2)<\/code> per page. On a directory it reports how much of the tree is resident and, with -v<\/code>, which individual files are fully or partly cached.<\/p>\n\n
apt install vmtouch\nvmtouch \/var\/www\/static          # summary: resident vs total\nvmtouch -v \/var\/www\/static | head -20   # per-file residency\nvmtouch -l \/var\/www\/static       # lock into RAM (needs CAP_IPC_LOCK)<\/code><\/pre>\n\n
After an hour of traffic vmtouch<\/code> reported 1,842 of 2,151 MB resident (85.6%), the missing 309 MB concentrated in 41 rarely-requested files \u2014 exactly what LRU should evict. That is more actionable than any global Cached<\/code> figure.<\/p>\n\n
vmtouch -l<\/code> pins page cache the kernel cannot reclaim. On this 3.8 GB box, locking 2.1 GB left 1.3 GB for the application and produced an OOM kill within four hours. Use -t<\/code> to preload without pinning, or keep the lock under 25% of RAM.<\/p>\n\n
Computing a hit ratio you can track over time<\/h2>\n\n
cachestat<\/code> gives one-second samples; to track a ratio over days, run it under a wrapper that emits a line per interval to your metrics agent, or sample \/proc\/vmstat<\/code> pgpgin<\/code> deltas against application read counts.<\/p>\n\n
# 60-second mean hit ratio, parsed from cachestat\ncachestat 1 60 | awk 'NR>2 {gsub(\/%\/,\"\",$4); h+=$4; n++} END {printf \"mean hit ratio: %.2f%% over %d samples\\n\", h\/n, n}'\n\n# per-process file read hit proxy via BPF (requires root)\nvfsstat 5 1<\/code><\/pre>\n\n
vfsstat 5 1<\/code> from bcc-tools breaks reads\/writes down by operation; a rising Read<\/code> rate with a flat Cached<\/code> growth is the signature of a working set that has outgrown RAM. Pair it with nstat -az | grep -i drop<\/code> if the source is a network mount rather than local disk.<\/p>\n\n
Reading the numbers: what a good ratio looks like<\/h2>\n\n
There is no universal target, but the shape of the distribution is informative. Below are the same box under three traffic levels, with the working set fixed at 2.1 GB and RAM at 3.8 GB.<\/p>\n\n
Traffic<\/th>cachestat hit ratio<\/th>vmtouch resident<\/th>Device read IOPS<\/th>p99 latency<\/th><\/tr><\/thead>
20 req\/s<\/td>98.1%<\/td>2,148 \/ 2,151 MB<\/td>38<\/td>9.4 ms<\/td><\/tr>
200 req\/s<\/td>97.4%<\/td>2,149 \/ 2,151 MB<\/td>410<\/td>11.2 ms<\/td><\/tr>
800 req\/s<\/td>94.8%<\/td>2,151 \/ 2,151 MB<\/td>1,720<\/td>19.8 ms<\/td><\/tr>
800 req\/s + 900 MB DB cache<\/td>71.3%<\/td>1,540 \/ 2,151 MB<\/td>9,300<\/td>63.0 ms<\/td><\/tr><\/tbody><\/table><\/figure>\n\n
The last row is the failure mode worth memorising: adding a database to the same 3.8 GB box pushed the asset working set out of cache, the resident fraction fell from 100% to 71.6%, and device read IOPS rose 5.4\u00d7. Nothing in free -h<\/code> flagged it \u2014 available<\/code> looked the same, because the pages had been reused rather than freed. Only the hit ratio and vmtouch<\/code> residency showed the cause.<\/p>\n\n
A ratio in the mid-90s with residency near 100% means more RAM buys nothing. A ratio below 90% with residency under 85% means the working set does not fit: shrink it or buy memory. In between, vmtouch -v<\/code> shows whether a few large files crowd out many small ones.<\/p>\n\n
Practical fixes when the ratio is low<\/h2>\n\n