README

Hprof Heap Dump parser
Eddie Aftandilian (eaftan@cs.tufts.edu)

This is the source code for a parser for Hprof heap dump files that can
be produced by various JVMs.  This code parses the binary format of these
files.  Documentation on the file format and the meanings of the different
record types can be found here:
http://blogs.sun.com/kto/resource/manual.html (older documentation)
$JVM/demo/jvmti/hprof/src/manual.html (if you have the Sun JDK installed)

The main functionality is in the HprofParser.java file, which parses the heap 
dump file and calls a method in the associated RecordHandler for each record 
parsed.  The RecordHandler interface is meant to be implemented to perform 
whatever analysis you like.  I recommend subclassing NullRecordHandler, which
does nothing for all records, and overriding only the methods for the record
types you are interested in.  By default, the Parse program uses the example
PrintHandler, which simply prints the data from each record.  To change to a 
different handler class, simply pass the command line option
"--handler=<classname>" to Parse, where classname is the fully-qualified
class name of the handler class.

I provide a sample heap dump from Dacapo antlr in the file java.hprof.

The build uses Maven (http://maven.apache.org/).  You can build it with the
following command:
$ maven compile

To produce a binary heap dump from the Oracle JVM, use the following command:
java -agentlib:hprof=heap=dump,format=b ToBeProfiledClass

This will dump the heap at the end of program execution.  See the 
documentation referenced above to see how to produce heap dumps at other 
points in program execution.

This code is released under the Apache 2.0 license.  See the LICENSE file in
this directory for details.