This example demonstrates how to create a pure Java-only agent which monitors the Java object heap using standard Java MX beans. The program then uses IBM's diagnostic com.ibm.jvm.Dump class to generate diagnostic data at a designated Java object heap utilization threshold.

This example can be configured to generate any or all of the following types of diagnostic data:

a. javacore files (a.k.a., thread dumps)
b. heapdump files (a.k.a., object dumps)
c. system files (a.k.a., process core dumps)

when the Java object heap utilization reaches a designated threshold.

Download this example using the following anonymous FTP URL:

ftp://ftp.software.ibm.com/aix/tools/java/tools/DumpAgent.tar.gz

Then copy the downloaded DumpAgent.tar.gz file to a temporary directory (e.g., /tmp/dumpagent) on your AIX system.

From a command prompt, execute the following commands to extract the contents of the downloaded DumpAgent.tar.gz file:

# cd TMP_PATH (e.g., cd /tmp/dumpagent)
# gunzip -c < DumpAgent.tar.gz | tar -xvf -

From a command prompt, execute the following commands to compile the example files extracted in the previous step:

# cd TMP_PATH (e.g., cd /tmp/dumpagent)
# export JAVA_HOME="JAVA_PARENT_DIR" (e.g., export JAVA_HOME="/usr/java8")
# make

From a command prompt, execute the following commands to demonstrate (or test) the features of this example:

# cd TMP_PATH (e.g., cd /tmp/dumpagent)
# export JAVA_HOME="JAVA_PARENT_DIR" (e.g., export JAVA_HOME="/usr/java8")

{Test creating javacore diagnostic files}
# make test_java

{Test creating heapdump diagnostic files}
# make test_heap

{Test creating process core files}
# make test_system

$ java -javaagent:dumpagent.jar="OPTIONS" MAIN_CLASS

where OPTIONS can be (all options are required):

-l
Confirms that the license.txt has been read and the conditions for use and support are understood

-d java|heap|system[,java|heap|system]
java = javacore
heap = heapdump
system = process core file

-t theshold_percent
threshold that represents the percentage (whole numbers only) of utilization of the Java object heap to trigger the generation of the diagnostic data.
(e.g., 80 = Java heap is 80% used)

-r range_start..range_stop
range_start = start range
range_stop = stop range
(e.g., 1..1 = generate 1 dump, 1..4 = generate 4 dumps)

The following example demonstrates how to generate two (-r1..2) javacore (-d java) and heapdump (-d heap) diagnostic files when the Java object heap utilization reaches 80% (-t 80) of a 200 MB (-Xmx200MB) heap size:

$ export CLASSPATH=/tmp/dumpagent:${CLASSPATH}
$ java -javagent:dumpagent.jar="-l -t 80 -djava,heap -r 1..2" -Xmx200MB com.ibm.examples.DumpAgentTest

This example was provided by Prakash Palaniappan, an IBM Java Software Engineer based in Bangalore, India.

IBM hopes that this example is helpful in your effort to monitor and troubleshoot your Java applications.

However, IBM and/or its affliates have no liability for the use of this agent. Use this agent at your own risk.

No support will be provided by IBM and/or any of its affliates for this sample code. Attempts to get support for this sample will be denied.