uobjnew: Add man page and companion examples file

man/man8/uobjnew.8

@@ -0,0 +1,79 @@
+.TH uobjnew 8 "2016-11-07" "USER COMMANDS"
+.SH NAME
+uobjnew \- Summarize object allocations in high-level languages.
+.SH SYNOPSIS
+.B uobjnew [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v] {java,ruby,c} pid [interval]
+.SH DESCRIPTION
+uobjnew traces object allocations in high-level languages (including "malloc")
+and prints summaries of the most frequently allocated types by number of 
+objects or number of bytes.
+
+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, the Java process
+must be started with the "-XX:+ExtendedDTraceProbes" flag.
+
+Since this uses BPF, only the root user can use this tool.
+.SH REQUIREMENTS
+CONFIG_BPF and bcc.
+.SH OPTIONS
+.TP
+\-C TOP_COUNT
+Print the top object types sorted by number of instances.
+.TP
+\-S TOP_SIZE
+Print the top object types sorted by size.
+.TP
+\-v
+Print the resulting BPF program, for debugging purposes.
+.TP
+{java,ruby,c}
+The language to trace.
+.TP
+pid
+The process id to trace.
+.TP
+interval
+Wait this many seconds and then print the summary and exit. By default, wait
+for Ctrl+C to exit.
+.SH EXAMPLES
+.TP
+Trace object allocations in a Ruby process:
+#
+.B uobjnew ruby 148
+.TP
+Trace object allocations from "malloc" and print the top 10 by total size:
+#
+.B uobjnew -S 10 c 1788
+.SH FIELDS
+.TP
+TYPE
+The object type being allocated. For C (malloc), this is the block size.
+.TP
+ALLOCS
+The number of objects allocated.
+.TP
+BYTES
+The number of bytes allocated.
+.SH OVERHEAD
+Object allocation events are quite frequent, and therefore the overhead from
+running this tool can be considerable. Use with caution and make sure to 
+test before using in a production environment. Nonetheless, even thousands of
+allocations per second will likely produce a reasonable overhead when 
+investigating a problem.
+.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
+ustat(8), ugc(8), memleak(8)

tools/uobjnew_example.txt

@@ -0,0 +1,74 @@
+Demonstrations of uobjnew.
+
+
+uobjnew summarizes new object allocation events and prints out statistics on
+which object type has been allocated frequently, and how many bytes of that
+type have been allocated. This helps diagnose common allocation paths, which
+can in turn cause heavy garbage collection.
+
+For example, trace Ruby object allocations when running some simple commands
+in irb (the Ruby REPL):
+
+# ./uobjnew ruby 27245
+Tracing allocations in process 27245 (language: ruby)... Ctrl-C to quit.
+
+TYPE # ALLOCS # BYTES
+NameError 1 0
+RubyToken::TkSPACE 1 0
+RubyToken::TkSTRING 1 0
+String 7 0
+RubyToken::TkNL 2 0
+RubyToken::TkIDENTIFIER 2 0
+array 55 129
+string 344 1348
+^C
+
+
+Plain C/C++ allocations (through "malloc") are also supported. We can't report
+the type being allocated, but we can report the object sizes at least. Also,
+print only the top 10 rows by number of bytes allocated:
+
+# ./uobjnew -S 10 c 27245
+Tracing allocations in process 27245 (language: c)... Ctrl-C to quit.
+
+TYPE # ALLOCS # BYTES
+block size 64 22 1408
+block size 992 2 1984
+block size 32 68 2176
+block size 48 48 2304
+block size 944 4 3776
+block size 1104 4 4416
+block size 160 32 5120
+block size 535 15 8025
+block size 128 112 14336
+block size 80 569 45520
+^C
+
+
+USAGE message:
+
+# ./uobjnew -h
+usage: uobjnew.py [-h] [-C TOP_COUNT] [-S TOP_SIZE] [-v]
+ {java,ruby,c} pid [interval]
+
+Summarize object allocations in high-level languages.
+
+positional arguments:
+ {java,ruby,c} language to trace
+ pid process id to attach to
+ interval print every specified number of seconds
+
+optional arguments:
+ -h, --help show this help message and exit
+ -C TOP_COUNT, --top-count TOP_COUNT
+ number of most frequently allocated types to print
+ -S TOP_SIZE, --top-size TOP_SIZE
+ number of largest types by allocated bytes to print
+ -v, --verbose verbose mode: print the BPF program (for debugging
+ purposes)
+
+examples:
+ ./uobjnew -l java 145 # summarize Java allocations in process 145
+ ./uobjnew -l c 2020 1 # grab malloc() sizes and print every second
+ ./uobjnew -l ruby 6712 -C 10 # top 10 Ruby types by number of allocations
+ ./uobjnew -l ruby 6712 -S 10 # top 10 Ruby types by total size