This document provides details for downloading, compiling, and using a custom Java agent to generate IBM Java diagnostic data (e.g., javacore files, heapdump files, and process core dumps) at designated Java object heap utilization thresholds when using IBM Java for AIX.

This example demonstrates how to use Java standard MX beans (e.g., getMemoryPoolMXBeans) and IBM Java's industry leading diagnostic capabilies to generate diagnostic data based on the Java object heap utilization. Combining the superior diagnostic capabilities of IBM Java with IBM's feature rich and free Java diagnostic tools:

IBM Health Center Tool
IBM Garbage Collection and Memory Visualizer (GCMV)
IBM HeapAnalyzer Tool
IBM Memory Analyzer Tool
Java Performance Advisor

empowers Java application developers to monitor and troubleshoot a wide range of situations.
Jump to section: (Disclaimer) (Overview) (Download) (Extract) (Compile) (Test) (Syntax) (Acknowledgements) (Support)
The instructions in this document make references to generic terms in Italics that will need to be replaced with information specific to the support call and the environment. It is very important that consistent and accurate values be used in place of the Italicized generic terms when collecting the data to ensure the prompt and correct delivery of the data when uploaded.
Generic Term Replace with
TMP_PATH A temporary path to storage and extract the download file(s). (e.g., /tmp/dumpagent)
JAVA_PARENT_DIR The parent directory of the IBM Java installation (e.g., /usr/java7)
Overview
Step-by-Step Instructions

Disclaimer

The DumpAgent.tar.gz file includes a license.txt file that clearly states that this example is provided AS-IS. Furthermore, IBM is not obligated to provide support or assistance with downloading, modifying, compiling, implementing, or debugging this example. All attempts to obtain support for this example will be denied.

Please read the license.txt to ensure that all disclaimers are understood before attempting to use this example.

Furthermore, this document assumes that the reader is familiar with and knows how to search, read and understand online documentation, for the concepts discussed (e.g., Java programming, compiling, creating jar files, executing Java programs, Java concepts, etc., )

Overview

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

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.

Extract

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 -

Compile

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

Test

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

Syntax

$ 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

Acknowledgements

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

Support

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.

Step 10:

ACTION

Step 11:

ACTION

Step 12:

ACTION

Step 13:

ACTION

Step 14:

ACTION

Step 15:

ACTION

Step 16:

ACTION

Step 17:

ACTION

Step 18:

ACTION

Step 19:

ACTION

Step 20:

ACTION

Step 21:

ACTION

Document Type: Instructional
Content Type: Howto
Hardware: all Power
Operating System: all AIX Versions
IBM Java: all Java Versions
Author(s): Roger Leuckie
Reviewer(s): Roger Leuckie
Click here to submit feedback for this document.