readme

IMPORTANT CAVEATS:

	THIS IS AN EXPERIMENTAL AGENT PROVIDED ON AN "AS-IS" BASIS WITH VERY LIMITED SUPPORT.
	IT ATTEMPTS TO INTERACT AS SAFELY AS POSSIBLE WITH CLASSIC AND HOTSPOT VMS, BUT COULD
	CONCEIVABLY CAUSE CRASHES OR HANGS - PARTICULARLY WHEN THE JVM IS UNDER STRESS.

	THEREFORE WE RECOMMEND IT SHOULD NOT BE USED IN A PRODUCTION/CRITICAL ENVIRONMENT.

	THE ACCURACY OF OBJECT AND REFERENCE DETAILS IN THE HEAPDUMP HAS NOT BEEN PROVED
	(ESPECIALLY FOR THE 1.2.2 CLASSIC AGENT) BUT DUMPS SHOULD CONTAIN ENOUGH INFORMATION
	TO PROFILE AND DIAGNOSE LEAKS IN THE JAVA HEAP.

Installation instructions:

	1)  Add the appropriate Jar file to the JVM classpath:

		CLASSPATH=<dir>/<VERSION>/IBM_HeapDump.jar:${CLASSPATH}; export CLASSPATH

	     or copy the appropriate Jar file into the JVM extensions folder:

		cp <dir>/<VERSION>/IBM_HeapDump.jar <JDK>/jre/lib/ext

             For WebSphere, go to...
          
                Application Servers > appserver > Process Definition > Java Virtual Machine 

             ...and create the following in the Classpath field...

                /path/to/IBM_HeapDump.jar


	2)  Add the folder containing the appropriate agent library to the JVM libpath:

		LD_LIBRARY_PATH=<dir>/<VERSION>:${LD_LIBRARY_PATH}; export LD_LIBRARY_PATH

	     or copy the appropriate agent library into the JVM library folder:

		cp <dir>/<VERSION>/libIBM_HeapDump.so <JDK>/jre/lib/sparc

            On WebSphere, put the libIBM_HeapDump.so file into...

               /opt/WebSphere/AppServer/java/jre/lib/sparc

	3)  Use the following JVM option to enable the agent:

		-XrunIBM_HeapDump

	4)  The following output should then appear on stdout / in the stdout log:

		IBM HeapDump agent for Solaris (v0.2)
		=====================================
		Loaded SymTable for libjvm.so
		.... various messages may appear ....
		=====================================

	5)  Signal the JVM whenever you wish to collect a heapdump:

		kill -HUP <JVM PID>

	     or use the programmatic interface provided by the jar file, ie:

		com.ibm.jvm.Dump.heap("my_heapdump.txt");


             The file should be created in the "Working Directory".  On WebSphere Solaris, the file
             will be something like...

                 /opt/WebSphere/AppServer/heapdump.1102024966.2916.txt

Users of the 64 bit JVM variant on 1.4.x (ie. java -d64 ...) should change step 2 to:

	2)  Add the folder containing the appropriate agent library to the JVM libpath:

		LD_LIBRARY_PATH=<dir>/<VERSION>/sparcv9:${LD_LIBRARY_PATH}; export LD_LIBRARY_PATH

	     or copy the appropriate agent library into the JVM library folder:

		cp <dir>/<VERSION>/sparcv9/libIBM_HeapDump.so <JDK>/jre/lib/sparcv9

32 bit heap dumps can be analyzed using the updated HeapRoots tool provided in the zip file (see hr201.jar).
Unfortunately this version of HeapRoots cannot analyze 64 bit dumps, but this should be fixed in a later release.

Detailed instructions for HeapRoots can be found on David Screen's website:

	http://w3.hursley.ibm.com/~screenda/heaproots/heaproots.html

Finally, note that the object flags at each JVM level vary according to what we can decode from the headers...

1.2.2 flags:

	L  -  object is currently locked
	W  -  object is not locked, but has waiting threads
	B  -  object is "meta-locked" (hash code not available)

1.3.1 flags:

	L  -  object is currently locked
	M  -  object has been marked by GC		[won't see this outside of GC]
	N  -  object is in the new generation
	O  -  object is in the old generation
	P  -  object is in the perm generation
	R  -  used in reference processing

1.4.1 flags:  (unfortunately there's less generational detail as the heap interface is more abstract)

	L  -  object is currently locked
	M  -  object has been marked by GC		[won't see this outside of GC]
	P  -  object is in the perm generation
	R  -  used in reference processing

1.4.2 flags:  (ditto)

	L  -  object is currently locked
	M  -  object has been marked by GC		[won't see this outside of GC]
	P  -  object is in the perm generation
	R  -  used in reference processing