HDUMP - Heap Dump Post-Processor

Overview
Using HDUMP
Delta HDUMP
PhdReader

Overview

HDUMP post-processes the information JPROF collects about the Java heap, in an attempt to locate memory leaks. Because Java uses a Garbage Collector that automatically deallocates unreferenced objects, memory leaks are not caused by forgetting to deallocate an object. Instead, they are the result of unnecessary references which keep objects alive.

HDUMP displays the following types of information to help identify these references:

• the shortest path to any object in the heap from some root of the heap
• the objects furthest from any root in the heap
• all of the roots and objects which reference an object

Using HDUMP

You use HDUMP by simply specifying the log-hd file which contains all of the heap information collected by JPROF:
hdump -f filename [parms]

If none of the optional parameters are specified, this will produce the following information:

• A list of the 10 classes with the most allocated objects
• A heapsum file showing the shortest reference path to the deepest object in each of those 10 classes
• A b1st file that enumerates all of the live objects in the heap, breadth-first, starting with the roots of the heap
• A lattice file that contains the complete lattice of object references.

All output files will use the same file extension as the log-hd file used as input.

After you have executed HDUMP once, you may want to invoke it again in interactive mode, using the -i parameter:

hdump -f filename -i

In interactive mode, you can specify the object id of any object that you find in the b1st file to view the shortest reference path to that object. This path is both displayed on the screen and appended to the heapsum file. These paths are extracted from the information in the b1st file and can be done very quickly.

After you have produced all of the shortest paths you want, you can specify objects using the r command to produce a listing of all of the objects which reference the selected object, using a breadth-first algorithm which works backwards from the object to the roots which reference it. This is actually a list of everything that is keeping this object alive. All of these listings are written to the b2nd file.

The processing for these reverse listings destroys the internal copy of the b1st data, so it is only done after the shortest path listings. These b2nd listings can also be selected by specifying the object id on the command line with the -r parameter for up to 32 objects:

hdump -f filename -r objid [-r objid ...]

For a full list of valid HDUMP parameters, simply enter hdump ? to display the help information. However, for those who wish to see this list in its current form, here it is:

Usage: hdump [options]

 -f hdfile
 -i        : interactive ShortestPath mode
 -r oid    : all objects reachable from oid using back
           : references (may be specified up to 32 times)
 -diff m n : delta between heapdumps m and n using log-hd.n+
             (may be specified up to 32 times)(JVMTI dumps only)
 -rdiff m n: delta between obj tags m and n
             (may be specified up to 32 times)(JVMTI dumps only)
 -iobj m   : ignore object w/ tag m when processing paths
             (may be specified up to 32 times)
 -iref m n : ignore references from m to n when processing paths
             (may be specified up to 32 times)
 -icls c   : ignore class with name c when processing paths
             (may be specified up to 32 times)
 -anc m,n..: find common ancestor of a comma-separated list of
             object tags, outputs to heapsum file
 -clsanc c : find common ancestors of all instances of class c
             outputs to heapsum file
 -nosoft   : do not expand java/lang/ref/SoftReference objects
 -noweak   : do not expand java/lang/ref/WeakReference objects
 -implied  : include roots implied by class references
 -compact  : suppress formatted and padded output
 -padded   : add padding to the lattice file
 -phd      : create log-phd from the log-hd input file
 -writecnm : create log-hdcnm file
 -unkroots : include all roots from log-hd input file
             including those listed for unknown reasons
 -verbose  : verbose messages to stderr
 -verbmsg  : verbose messages to hdump-msg

Results: 

 heapsum   - trace back(obj->root) of selected objects
 b1st      - Breadth first tree from All roots.
             Objects are minimum distance from any root
 b2nd      - All objects reachable via back references
             Output from -r and interactive r commands
 b3rd      - Breadth first tree TO a selected set of objects
             only FROM the roots that referenced them.
             Output from -diff hd.m hd.n and -rdiff m n
 liveobjs  - All objects reachable via roots
 orphans   - All objects not reachable via roots
 lattice   - Parent/Self/Child info
 roots     - All roots of the heap (-verbose only)
 log-hdcnm - Class summary file (-writecnm only)

Delta HDUMP

Delta HDUMP is available when using JPROF with JVMTI. Each log-hd.n file contains information about the highest object tag in use at the time of each preceding heap dump. Thus, we can easily tell which objects were created between heapdumps. By using the "-diff m n" parameter, the user can select which pair of heap dumps to compare. The result of this comparison is the b3rd file.

The format of the b3rd file is the same as the b1st file. However, the roots used in the b3rd file are those found using the b2nd algorithm with all of the objects created between heapdumps m and n. Furthermore, only those objects referenced in the b2nd search that determined those roots are included in the b3rd output. The result is a greatly reduced subset of the b1st file that includes only those references that are keeping these new objects alive.

PhdReader

PhdReader makes it possible to use HDUMP to post-process heap dumps in Portable Heap Dump (PHD) format by converting .phd files to a log-hd file. It uses svcdump.jar, which must be downloaded. The run.PhdReader command script will invoke PhdReader with the jar file.

Because log-hdcnm is generated by JPROF at the same time as log-hd, the -writecnm option was added to HDUMP to produce a log-hdcnm file from a log-hd file.