Add example and man file for llcstat

man/man8/llcstat.8

@@ -0,0 +1,69 @@
+.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

@@ -0,0 +1,42 @@
+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