This debugging tool enables you to read and analyze the new -Xhprof files that are generated by JDKTM 1.2 as of the Beta 3 release. The Heap Analysis Tool (HAT) helps to debug unnecessary object retention (sometimes imprecisely called "memory leaks") by providing a convenient means to browse the object topology in a heap snapshot, which is generated by the Java VM. HAT reads a hprof file, then sets itself up as a web server--therefore allowing you to run queries agains a heap dump contained within the hprof file.
Please do understand that this is a prototype. I do not consider HAT to be of production quality. I think the UI is somewhat clumsy and unpolished (OK, it's a quick and dirty hack :-) More seriously, HAT is fairly memory-intensive. Expect HAT to require three times more RAM than the program being debugged. I can think of solutions for this, but I'll leave that as an exercise for the tool vendor -- I have a day job, too! Despite these limitations, I hope you'll find HAT useful.
Both source and a binary of HAT are available as part of an on-line training book. Check out Advanced Programming Book's chapter on Profiling. If that doesn't work, it should be available on this J2EE resources page. If that fails, I made copies here of the Binary or the Source.
The heap profile file that you give to hat must be in binary format. This is done withe the "format=b" modifier to the -Xhprof command line. For example, to run the program Main, this command will work:
java -Xhprof:file=dump.hprof,format=b Main
One feature of the JVM* is that you can request a heap dump over a socket. This can be useful for remote debugging of devices that don't have file systems, for example. To use this feature, you run a program that listens on a port on some machine (call it port 7001 on "fido"), and then you invoke the JVM like this:
java -Xhprof:net=fido:7001,format=b
The JVM then connects to port 7001 on fido, and that program can send it a command to generate a heap dump.
I wrote a quick hack to request these dumps. It's called NetDumper, and you can download it here.
I get occasional reports of errors reading .hprof files generated with 1.3 and 1.4 VMs. Usually, it's an IOException, with a message about "Stack trace not found ...".
This is the result of a bug in the VM: It is generating an improperly formatted .hprof file. To work around the problem, there are some command-line options you can provide to the VM generating the file that may help. I'm told the "-classic" option often results in a well-formatted .hprof file. Setting "-stack=false" seems to be necessary, at least with some JDK releases.
If these fail, try a different JDK release, or a different platform -- results are often different between Solaris and Win32, for example.
I have received reports that the JDK 1.2 Solaris Production Release does not have a way of adding a heap dump to a .hprof file. On the JDK Win32 Production Release this is done with ctrl-break; on the JDK Solaris Reference Implementation this is done with ctrl-backslash. This is a known bug, and has been submitted as bug number 4204089.
One possible workaround is to use the dump generator program, described above. Unfortunately, I've received a report that this results in a segmentation fault in the target VM, at least under Solaris x86. This has been submitted as bug number 4204501.
Some versions of the production VM had a problem with the contents of the heap dump. This was submitted as bug number 4213660, and is marked as fixed. I'm not sure if the fix has been released at this time. A similar bug in the production VM is bug 4225829. As of this writing (April 8, 1999) this bug has not been fixed.
The JDK Solaris Reference Implementation (JDK 1.2) does not appear to share these problems. It is available for both Sparc Solaris and x86 Solaris, and can be downloaded from http://java.sun.com/products/.
There is a bug in the Win32 version of JDK 1.2beta3 that causes it to output corrupt .hprof files. This has been fixed in 1.2beta4. If you're still using 1.2beta3, You can read more about it and download a workaround here.
*As used on this web site, the terms "Java virtual machine" or "JVM" mean a virtual machine for the Java platform.