[cachetop] fix and doc

* pass -fno-color-diagnostics to clang
* remove unicode import (#623)
* add time to cachetop output
* add keybindings to cachetop.8
* add cachetop links to README.md

README.md

@@ -79,6 +79,7 @@ Examples:
 - tools/[btrfsdist](tools/btrfsdist.py): Summarize btrfs operation latency distribution as a histogram. [Examples](tools/btrfsdist_example.txt).
 - tools/[btrfsslower](tools/btrfsslower.py): Trace slow btrfs operations. [Examples](tools/btrfsslower_example.txt).
 - tools/[cachestat](tools/cachestat.py): Trace page cache hit/miss ratio. [Examples](tools/cachestat_example.txt).
+- tools/[cachetop](tools/cachetop.py): Trace page cache hit/miss ratio by processes. [Examples](tools/cachetop_example.txt).
 - tools/[cpudist](tools/cpudist.py): Summarize on- and off-CPU time per task as a histogram. [Examples](tools/cpudist_example.txt)
 - tools/[dcsnoop](tools/dcsnoop.py): Trace directory entry cache (dcache) lookups. [Examples](tools/dcsnoop_example.txt).
 - tools/[dcstat](tools/dcstat.py): Directory entry cache (dcache) stats. [Examples](tools/dcstat_example.txt).

man/man8/cachetop.8

@@ -7,13 +7,28 @@ cachetop \- Statistics for linux page cache hit/miss ratios per processes. Uses
 .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.
+and looking for patterns in operation usage over time. It provides a \fBtop\fR-like interface
+which by default sorts by \fBHITS\fR in ascending order.
 
 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 KEYBINDINGS
+The following keybindings can be used to control the output of \fBcachetop\fR.
+.TP
+.B <
+Use the previous column for sorting.
+.TP
+.B >
+Use the next column for sorting.
+.TP
+.B r
+Toggle sorting order (default ascending).
+.TP
+.B q
+Quit cachetop.
 .SH REQUIREMENTS
 CONFIG_BPF and bcc.
 .SH EXAMPLES

src/cc/frontends/clang/loader.cc

@@ -99,9 +99,12 @@ int ClangLoader::parse(unique_ptr<llvm::Module> *mod, unique_ptr<vector<TableDes
       abs_file = string(dstack.cwd()) + "/" + file;
   }
 
+  // -fno-color-diagnostics: this is a workaround for a bug in llvm terminalHasColors() as of
+  // 22 Jul 2016. Also see bcc #615.
   vector<const char *> flags_cstr({"-O0", "-emit-llvm", "-I", dstack.cwd(),
                                    "-Wno-deprecated-declarations",
                                    "-Wno-gnu-variable-sized-type-not-at-end",
+                                   "-fno-color-diagnostics",
                                    "-x", "c", "-c", abs_file.c_str()});
 
   KBuildHelper kbuild_helper(kdir);

tools/cachetop.py

@@ -14,10 +14,13 @@
 
 from __future__ import absolute_import
 from __future__ import division
-from __future__ import unicode_literals
+# Do not import unicode_literals until #623 is fixed
+# from __future__ import unicode_literals
 from __future__ import print_function
-from collections import defaultdict
+
 from bcc import BPF
+from collections import defaultdict
+from time import strftime
 
 import argparse
 import curses
@@ -210,7 +213,9 @@ def handle_loop(stdscr, args):
         stdscr.clear()
         stdscr.addstr(
             0, 0,
-            "Buffers MB: %.0f / Cached MB: %.0f" % (buff, cached)
+            "%-8s Buffers MB: %.0f / Cached MB: %.0f" % (
+                strftime("%H:%M:%S"), buff, cached
+            )
         )
 
         # header

tools/cachetop_example.txt

@@ -15,7 +15,7 @@ examples:
     ./cachetop 1           # print every second hit/miss stats
 
 # ./cachetop 5
-Buffers MB: 76 / Cached MB: 114
+13:01:01 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%
@@ -43,7 +43,7 @@ Command used to generate the activity
 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
+13:01:01 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%
@@ -57,7 +57,7 @@ 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
+13:01:01 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%