ustat: Add man page and companion example file
diff --git a/man/man8/ustat.8 b/man/man8/ustat.8
new file mode 100644
index 0000000..a55ee09
--- /dev/null
+++ b/man/man8/ustat.8
@@ -0,0 +1,116 @@
+.TH ustat 8 "2016-11-07" "USER COMMANDS"
+.SH NAME
+ustat \- Activity stats from high-level languages.
+.SH SYNOPSIS
+.B ustat [-l {java,python,ruby,node}] [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval [count]]
+.SH DESCRIPTION
+This is "top" for high-level language events, such as garbage collections,
+exceptions, thread creations, object allocations, method calls, and more. The
+events are aggregated for each process and printed in a top-like table, which
+can be sorted by various fields.
+
+This uses in-kernel eBPF maps to store per process summaries for efficiency.
+
+This tool relies on USDT probes embedded in many high-level languages, such as
+Node, Java, Python, and Ruby. It requires a runtime instrumented with these
+probes, which in some cases requires building from source with a USDT-specific
+flag, such as "--enable-dtrace" or "--with-dtrace". For Java, some probes are
+not enabled by default, and can be turned on by running the Java process with
+the "-XX:+ExtendedDTraceProbes" flag.
+
+Newly-created processes will only be traced at the next interval. If you run
+this tool with a short interval (say, 1-5 seconds), this should be virtually
+unnoticeable. For longer intervals, you might miss processes that were started
+and terminated during the interval window.
+
+Since this uses BPF, only the root user can use this tool.
+.SH REQUIREMENTS
+CONFIG_BPF and bcc.
+.SH OPTIONS
+.TP
+\-l {java,python,ruby,node}
+The language to trace. By default, all languages are traced.
+.TP
+\-C
+Do not clear the screen between updates.
+.TP
+\-S {cload,excp,gc,method,objnew,thread}
+Sort the output by the specified field.
+.TP
+\-r MAXROWS
+Do not print more than this number of rows.
+.TP
+\-d
+Print the resulting BPF program, for debugging purposes.
+.TP
+interval
+Interval between updates, seconds.
+.TP
+count
+Number of interval summaries.
+.SH EXAMPLES
+.TP
+Summarize activity in high-level languages, 1 second refresh:
+#
+.B ustat
+.TP
+Don't clear the screen, and top 8 rows only:
+#
+.B ustat -Cr 8
+.TP
+5 second summaries, 10 times only:
+#
+.B ustat 5 10
+.SH FIELDS
+.TP
+loadavg
+The contents of /proc/loadavg
+.TP
+PID
+Process ID.
+.TP
+CMDLINE
+Process command line (often the second and following arguments will give you a
+hint as to which application is being run.
+.TP
+METHOD/s
+Count of method invocations during interval.
+.TP
+GC/s
+Count of garbage collections during interval.
+.TP
+OBJNEW/s
+Count of objects allocated during interval.
+.TP
+CLOAD/s
+Count of classes loaded during interval.
+.TP
+EXC/s
+Count of exceptions thrown during interval.
+.TP
+THR/s
+Count of threads created during interval.
+.SH OVERHEAD
+When using this tool with high-frequency events, such as method calls, a very
+significant slow-down can be expected. However, many of the high-level
+languages covered by this tool already have a fairly high per-method invocation
+cost, especially when running in interpreted mode. For the lower-frequency
+events, such as garbage collections or thread creations, the overhead should
+not be significant. Specifically, when probing Java processes and not using the
+"-XX:+ExtendedDTraceProbes" flag, the most expensive probes are not emitted,
+and the overhead should be acceptable.
+.SH SOURCE
+This is from bcc.
+.IP
+https://github.com/iovisor/bcc
+.PP
+Also look in the bcc distribution for a companion _example.txt file containing
+example usage, output, and commentary for this tool.
+.SH OS
+Linux
+.SH STABILITY
+Unstable - in development.
+.SH AUTHOR
+Sasha Goldshtein
+.SH SEE ALSO
+trace(8), argdist(8), tplist(8)
diff --git a/tools/ustat_example.txt b/tools/ustat_example.txt
new file mode 100644
index 0000000..7da01e6
--- /dev/null
+++ b/tools/ustat_example.txt
@@ -0,0 +1,78 @@
+Demonstrations of ustat.
+
+
+ustat is a "top"-like tool for monitoring events in high-level languages. It
+prints statistics about garbage collections, method calls, object allocations,
+and various other events for every process that it recognizes with a Java,
+Python, Ruby, or Node runtime.
+
+For example:
+
+# ./ustat.py
+Tracing... Output every 10 secs. Hit Ctrl-C to end
+12:17:17 loadavg: 0.33 0.08 0.02 5/211 26284
+
+PID CMDLINE METHOD/s GC/s OBJNEW/s CLOAD/s EXC/s THR/s
+3018 node/node 0 3 0 0 0 0
+^C
+Detaching...
+
+
+If desired, you can instruct ustat to print a certain number of entries and
+exit, which can be useful to get a quick picture on what's happening on the
+system over a short time interval. Here, we ask ustat to print 5-second
+summaries 12 times (for a total time of 1 minute):
+
+# ./ustat.py -C 5 12
+Tracing... Output every 5 secs. Hit Ctrl-C to end
+12:18:26 loadavg: 0.27 0.11 0.04 2/336 26455
+
+PID CMDLINE METHOD/s GC/s OBJNEW/s CLOAD/s EXC/s THR/s
+3018 node/node 0 1 0 0 0 0
+
+12:18:31 loadavg: 0.33 0.12 0.04 2/336 26456
+
+PID CMDLINE METHOD/s GC/s OBJNEW/s CLOAD/s EXC/s THR/s
+3018 node/node 0 0 0 0 0 0
+26439 java -XX:+ExtendedDT 2776045 0 0 0 0 0
+
+12:18:37 loadavg: 0.38 0.14 0.05 2/336 26457
+
+PID CMDLINE METHOD/s GC/s OBJNEW/s CLOAD/s EXC/s THR/s
+3018 node/node 0 0 0 0 0 0
+26439 java -XX:+ExtendedDT 2804378 0 0 0 0 0
+
+(...more output omitted for brevity)
+
+
+USAGE message:
+
+# ./ustat.py -h
+usage: ustat.py [-h] [-l {java,python,ruby,node}] [-C]
+ [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d]
+ [interval] [count]
+
+Activity stats from high-level languages.
+
+positional arguments:
+ interval output interval, in seconds
+ count number of outputs
+
+optional arguments:
+ -h, --help show this help message and exit
+ -l {java,python,ruby,node}, --language {java,python,ruby,node}
+ language to trace (default: all languages)
+ -C, --noclear don't clear the screen
+ -S {cload,excp,gc,method,objnew,thread}, --sort {cload,excp,gc,method,objnew,thread}
+ sort by this field (descending order)
+ -r MAXROWS, --maxrows MAXROWS
+ maximum rows to print, default 20
+ -d, --debug Print the resulting BPF program (for debugging
+ purposes)
+
+examples:
+ ./ustat # stats for all languages, 1 second refresh
+ ./ustat -C # don't clear the screen
+ ./ustat -l java # Java processes only
+ ./ustat 5 # 5 second summaries
+ ./ustat 5 10 # 5 second summaries, 10 times only