| .TH cachestat 8 "2016-01-30" "USER COMMANDS" |
| .SH NAME |
| cachestat \- Statistics for linux page cache hit/miss ratios. Uses Linux eBPF/bcc. |
| .SH SYNOPSIS |
| .B cachestat |
| [-T] [interval [count]] |
| .SH DESCRIPTION |
| This traces four kernel functions and prints per-second summaries. This can |
| be useful for general workload characterization, and looking for patterns |
| in operation usage over time. |
| |
| This works by tracing kernel page cache functions using dynamic tracing, and will |
| need updating to match any changes to these functions. Edit the script to |
| customize which functions are traced. |
| |
| Since this uses BPF, only the root user can use this tool. |
| .SH REQUIREMENTS |
| CONFIG_BPF and bcc. |
| .SH EXAMPLES |
| .TP |
| Print summaries every second: |
| # |
| .B cachestat |
| .TP |
| Print summaries every second with timestamp: |
| # |
| .B cachestat -T |
| .TP |
| Print output every five seconds, three times: |
| # |
| .B cachestat 5 3 |
| .TP |
| Print output with timestamp every five seconds, three times: |
| # |
| .B cachestat -T 5 3 |
| .SH FIELDS |
| .TP |
| TIME |
| Timestamp. |
| .TP |
| HITS |
| Number of page cache hits. |
| .TP |
| MISSES |
| Number of page cache misses. |
| .TP |
| DIRTIES |
| Number of dirty pages added to the page cache. |
| .TP |
| HITRATIO |
| The hit ratio as a percentage. |
| .TP |
| READ_HIT% |
| Read hit percent of page cache usage. |
| .TP |
| WRITE_HIT% |
| Write hit percent of page cache usage. |
| .TP |
| BUFFERS_MB |
| Buffers size taken from /proc/meminfo. |
| .TP |
| CACHED_MB |
| Cached amount of data in current page cache taken from /proc/meminfo. |
| .SH OVERHEAD |
| 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, this is still a relatively efficient way to trace |
| these events, and so the overhead is expected to be small for normal workloads. |
| Measure in a test environment. |
| .SH SOURCE |
| This is from bcc. |
| .IP |
| https://github.com/iovisor/bcc |
| .PP |
| Also look in the bcc distribution for a companion _examples.txt file containing |
| example usage, output, and commentary for this tool. |
| .SH OS |
| Linux |
| .SH STABILITY |
| Unstable - in development. |
| .SH AUTHOR |
| Allan McAleavy |
| .SH SEE ALSO |
| https://github.com/brendangregg/perf-tools/blob/master/fs/cachestat |
