Add example and man file for llcstat

man/man8/llcstat.8

+.TH llcstat 8  "2015-08-18" "USER COMMANDS"
+.SH NAME
+llcstat \- Trace cache references and cache misses. Uses Linux eBPF/bcc.
+.SH SYNOPSIS
+.B llcstat [\-h] [\-c SAMPLE_PERIOD] [duration]
+.SH DESCRIPTION
+llcstat traces cache references and cache misses system-side, and summarizes
+them by PID and CPU. These events have different meanings on different
+architecture. For x86-64, they mean misses and references to LLC.
+This can be useful to locate and debug performance issues
+caused by cache hit rate.
+
+This works by sampling corresponding events defined in uapi/linux/perf_event.h,
+namely PERF_COUNT_HW_CACHE_REFERENCES and PERF_COUNT_HW_CACHE_MISSES, using
+BPF perf event tracing. Upon each sampled event, the attached BPF program
+records the PID and CPU ID on which the event happened, and stores it in table.
+
+This makes use of a Linux 4.9 feature (BPF_PROG_TYPE_PERF_EVENT).
+
+Since this uses BPF, only the root user can use this tool.
+.SH REQUIREMENTS
+CONFIG_BPF and bcc.
+.SH OPTIONS
+.TP
+\-h
+Print usage message.
+.TP
+\-c SAMPLE_PERIOD
+Sample one in this many cache reference and cache miss events.
+.TP
+duration
+Duration to trace, in seconds.
+.SH EXAMPLES
+.TP
+Sample one in 100 events, trace for 20 seconds:
+#
+.B llcstat -c 100 20
+.SH FIELDS
+.TP
+PID
+Process ID
+.TP
+NAME
+Process name
+.TP
+CPU
+CPU ID
+.TP
+REFERENCE
+Number of cache reference events
+.TP
+MISS
+Number of cache miss events
+.TP
+HIT%
+Cache hit ratio
+.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
+Teng Qin

tools/llcstat_example.txt

+Demonstrations of llcstat.
+
+llcstat traces cache reference and cache miss events system-wide, and summarizes
+them by PID and CPU.
+These events, defined in uapi/linux/perf_event.h, have different meanings on
+different architecture. For x86-64, they mean misses and references to LLC.
+
+Example output:
+
+# ./llcstat.py 20 -c 5000
+Running for 20 seconds or hit Ctrl-C to end.
+PID      NAME             CPU     REFERENCE         MISS   HIT%
+0        swapper/15       15        3515000       640000  81.79%
+238      migration/38     38           5000            0 100.00%
+4512     ntpd             11           5000            0 100.00%
+150867   ipmitool         3           25000         5000  80.00%
+150895   lscpu            17         280000        25000  91.07%
+151807   ipmitool         15          15000         5000  66.67%
+150757   awk              2           15000         5000  66.67%
+151213   chef-client      5         1770000       240000  86.44%
+151822   scribe-dispatch  12          15000            0 100.00%
+123386   mysqld           5            5000            0 100.00%
+[...]
+Total References: 518920000 Total Misses: 90265000 Hit Rate: 82.61%
+
+This shows each PID's cache hit rate during the 20 seconds run period.
+
+USAGE message:
+
+# ./llcstat.py --help
+usage: llcstat.py [-h] [-c SAMPLE_PERIOD] [duration]
+
+Summarize cache references and misses by PID
+
+positional arguments:
+  duration                Duration, in seconds, to run
+
+  optional arguments:
+    -h, --help            show this help message and exit
+    -c SAMPLE_PERIOD, --sample_period SAMPLE_PERIOD
+                          Sample one in this many number of cache reference
+                          and miss events