Skip to content

Commit

Permalink
[cachetop] add example and man page.
Browse files Browse the repository at this point in the history 
make interval a positional parameter.
  • Loading branch information
@chantra
chantra committed Jul 23, 2016
1 parent a021fd8 commit 75dfd5a
Show file tree
Hide file tree
Showing 3 changed files with 152 additions and 3 deletions.
76 changes: 76 additions & 0 deletions man/man8/cachetop.8
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
.TH cachetop 8 "2016-01-30" "USER COMMANDS"
.SH NAME
cachetop \- Statistics for linux page cache hit/miss ratios per processes. Uses Linux eBPF/bcc.
.SH SYNOPSIS
.B cachetop
[interval]
.SH DESCRIPTION
This traces four kernel functions and prints per-processes summaries every
\fBinterval\fR seconds. This can be useful for processes 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
Update summaries every five second:
#
.B cachetop
.TP
Print summaries each second:
#
.B cachetop 1
.SH FIELDS
.TP
PID
Process ID of the process causing the cache activity.
.TP
UID
User ID of the process causing the cache activity.
.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
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
Emmanuel Bretelle
.SH SEE ALSO
cachestat (8)
9 changes: 6 additions & 3 deletions tools/cachetop.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ def handle_loop(stdscr, args):
for i, stat in enumerate(process_stats):
stdscr.addstr(
i + 2, 0,
"{0:8} {username:8} {2:16} {3:8} {4:8} "
"{0:8} {username:8.8} {2:16} {3:8} {4:8} "
"{5:8} {6:9.1f}% {7:9.1f}%".format(
*stat, username=pwd.getpwuid(int(stat[1]))[0]
)
Expand All @@ -239,9 +239,12 @@ def handle_loop(stdscr, args):


def parse_arguments():
parser = argparse.ArgumentParser()
parser = argparse.ArgumentParser(
description='show Linux page cache hit/miss statistics including read '
'and write hit % per processes in a UI like top.'
)
parser.add_argument(
'--interval', '-i', type=int, default=5, nargs='?',
'interval', type=int, default=5, nargs='?',
help='Interval between probes.'
)

Expand Down
70 changes: 70 additions & 0 deletions tools/cachetop_example.txt
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# ./cachetop -h
usage: cachetop.py [-h] [interval]

show Linux page cache hit/miss statistics including read and write hit % per
processes in a UI like top.

positional arguments:
interval Interval between probes.

optional arguments:
-h, --help show this help message and exit

examples:
./cachetop # run with default option of 5 seconds delay
./cachetop 1 # print every second hit/miss stats

# ./cachetop 5
Buffers MB: 76 / Cached MB: 114
PID UID CMD HITS MISSES DIRTIES READ_HIT% WRITE_HIT%
1 root systemd 2 0 0 100.0% 0.0%
680 root vminfo 3 4 2 14.3% 42.9%
567 syslog rs:main Q:Reg 10 4 2 57.1% 21.4%
986 root kworker/u2:2 10 2457 4 0.2% 99.5%
988 root kworker/u2:2 10 9 4 31.6% 36.8%
877 vagrant systemd 18 4 2 72.7% 13.6%
983 root python 148 3 143 3.3% 1.3%
981 root strace 419 3 143 65.4% 0.5%
544 messageb dbus-daemon 455 371 454 0.1% 0.4%
243 root jbd2/dm-0-8 457 371 454 0.4% 0.4%
985 root (mount) 560 2457 4 18.4% 81.4%
987 root systemd-udevd 566 9 4 97.7% 1.2%
988 root systemd-cgroups 569 9 4 97.8% 1.2%
986 root modprobe 578 9 4 97.8% 1.2%
287 root systemd-journal 598 371 454 14.9% 0.3%
985 root mount 692 2457 4 21.8% 78.0%
984 vagrant find 9529 2457 4 79.5% 20.5%

Above shows the run of `find /` on a newly booted system.

Command used to generate the activity
# find /

Below shows the hit rate increases as we run find a second time and it gets it
its pages from the cache.
# ./cachetop.py
Buffers MB: 76 / Cached MB: 115
PID UID CMD HITS MISSES DIRTIES READ_HIT% WRITE_HIT%
544 messageb dbus-daemon 2 2 1 25.0% 50.0%
680 root vminfo 2 2 1 25.0% 50.0%
243 root jbd2/dm-0-8 3 2 1 40.0% 40.0%
1068 root python 5 0 0 100.0% 0.0%
1071 vagrant bash 350 0 0 100.0% 0.0%
1071 vagrant find 12959 0 0 100.0% 0.0%


Below shows that the dirty pages increases as a file of 80M is created running
# dd if=/dev/urandom of=/tmp/c bs=8192 count=10000

# ./cachetop.py 10
Buffers MB: 77 / Cached MB: 193
PID UID CMD HITS MISSES DIRTIES READ_HIT% WRITE_HIT%
544 messageb dbus-daemon 9 10 7 10.5% 15.8%
680 root vminfo 9 10 7 10.5% 15.8%
1109 root python 22 0 0 100.0% 0.0%
243 root jbd2/dm-0-8 25 10 7 51.4% 8.6%
1070 root kworker/u2:2 85 0 0 100.0% 0.0%
1110 vagrant bash 366 0 0 100.0% 0.0%
1110 vagrant dd 42183 40000 20000 27.0% 24.3%

The file copied into page cache was named /tmp/c with a size of 81920000 (81920000/4096) = 20000

0 comments on commit 75dfd5a

Please sign in to comment.