NAME

       cachestat - Measure page cache hits/misses. Uses Linux ftrace.

SYNOPSIS

       cachestat [-Dht] [interval]

DESCRIPTION

       This tool provides basic cache hit/miss statistics for the Linux page cache.

       Its  current  implementation uses Linux ftrace dynamic function profiling to create custom
       in-kernel counters, which is a workaround until such  counters  can  be  built-in  to  the
       kernel. Specifically, four kernel functions are counted:

              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

       It  is  possible  that  these functions have been renamed (or are different logically) for
       your kernel version, and this script will not work as-is.  This was written  for  a  Linux
       3.13 kernel, and tested on a few others 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). 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.

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

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.

AUTHOR

       Brendan Gregg

SEE ALSO

       iostat(1), iosnoop(8)