The Java heap is the memory space where the Java Virtual Machine (JVM) stores the entire set of objects created by the running Java application. A JVM heapdump is a file produced by the JVM to record the state of the heap at a particular moment in time. Many modern JVMs can be configured to produce such a file automatically on an Out-of-Memory (OOM) condition. Some JVMs also allow such a file to be created on demand.
JProbe allows you to import JVM heapdump files produced from various JVMs for detailed analysis. JProbe can import HPROF binary heapdumps from Sun and Sun-compatible JVMs (such as HP Java). JProbe can also import IBM Java SDK heapdump files in either of two supported formats: TXT or PHD (Portable Heapdump).
This capability can be used to diagnose problems with systems where the collection of more detailed memory snapshots with JProbe is not possible. Production systems where JProbe cannot be used due to overhead concerns or security policies, or other systems where memory problems are intermittent, are good candidates for this type of analysis.
We抣l explore how to configure IBM JVMs to produce heapdump files, how to generate these files on demand or during an Out-of-Memory (OOM) condition, and how to import them into JProbe Memory for analysis.
Configuring your JVM to produce a heapdump
Exact steps for configuring your JVM to produce a heapdump may vary by JVM, for precise instructions please consult your JVM vendor抯 documentation. Below we抣l describe typical settings. This information is also provided in the JProbe Reference Guide.
Environment variables control the IBM JVM抯 heap dump behavior. To enable the JVM to produce heapdumps on demand, you may need to set either, or both, of the following environment variables:
IBM_HEAP_DUMP=true
IBM_HEAPDUMP=true
If you want to have the JVM create a heapdump file and/or a javacore automatically on an Out-of-Memory (OOM) condition, set the following additional environment variables:
IBM_HEAPDUMP_OUTOFMEMORY=true
IBM_JAVACORE_OUTOFMEMORY=true
Note that more recent IBM JVMs set these latter two environment variables automatically. If you want to disable the automatic heapdump and/or javacore on OOM, you can set either or both of these environment variables to 慺alse�.
IBM JVMs generate the heapdump in one of two possible formats: a text-based heapdump, or a binary format 損ortable heapdump� (PHD) which is more suitable for cross-platform use. If you want to have the JVM create a heapdump file in text format, set the following additional environment variable to 憈rue�:
IBM_JAVA_HEAPDUMP_TEXT=true
The default setting is false, which will produce a PHD format heapdump file.
You may also wish to specify the heapdump location with an optional environment variable:
IBM_HEAPDUMPDIR=<directory>
Note that the names of these environment variables must be set entirely in upper case on UNIX and Linux operating systems.
Obtaining the Java heapdump
Once you have configured your environment variables as described above, start the application normally. You do not need to instrument your JVM with JProbe or to have JProbe on the target system.
If you are investigating an OOM condition, you may wish to run the system until the OOM occurs, and then look for the resulting TXT or PHD file. In most cases it is not necessary to wait for an OOM to detect problematic conditions in the Java heap � patterns will be evident long before the problem causes a chronic failure. To request a heapdump 憃n the fly� you can send a special signal to the IBM JVM.
On UNIX and Linux, the corresponding signal is SIGQUIT, which is typically sent to the process with a KILL 朡UIT command. The following screenshots show this series of steps in a Linux bash shell:
1. Use the export command to set the environment variables:
export IBM_HEAP_DUMP=true
export IBM_HEAPDUMP=true
We won抰 set so IBM_JAVA_HEAPDUMP_TEXT and as a result, we抣l get a PHD heapdump.
2. Run the Java application normally. Here we use an IBM Java 2 SE runtime version 1.5.0 to run the JProbe 揕eakExample� demo program.
![]()
3. In a new command line terminal window, find the process ID of the JVM running your application (LeakExample in this case) by using the ps command. Here we used ps ux | grep java
4. Issue the SIGQUIT to the JVM using the kill -QUIT command � specifically, kill 朡UIT
![]()
5. Observe that the JVM reports the heap dump event (and the java core dump) to the original command window, including the complete file path.
![]()
6. In the JProbe Console use File / Import to import the PHD heapdump file.
7. Use JProbe Memory抯 views to investigate the problem.
On Windows, a heapdump is requested by sending SIGBREAK to the Java process. If the Java process is running from a command window, you can use the Ctrl + Break keyboard combination to produce a SIGBREAK signal. If the process is run indirectly, as is often the case with WebSphere Application Server, you will need an indirect method to send a SIGBREAK signal to the Java process. Windows does not include a command for this specific purpose, but numerous freeware and commercial utilities are available.
Obtaining the Java heapdump from IBM WebSphere Application Server
Obtaining a heapdump from WebSphere Application Server is very similar to the process described above. You must set up the environment variables before the application server runs. You will need to identify the process ID of the server you wish to examine, and then send it the appropriate signal.
The JVM抯 stderr output appears in the application server log file. For example, a Windows system running WebSphere ND 6.0.2.3 on IBM Java SDK 1.4.2 had its environment configured to produce an IBM TXT heapdump. One application server was then started. The application server process was sent a SIGBREAK and this information appeared in native_stderr.log located at E:\IBM\WebSphereND\AppServer\profiles\AppSrv01\logs\server1
JVMDG217: Dump Handler is Processing Signal 21 - Please Wait.
JVMDG312: Dump Handler forcing GC for Heap dump...
JVMDG320: Requested old-style text heapdump
JVMDG315: JVM Requesting Heap dump file
JVMDG318: Heap dump file written to c:\temp\\heapdump.20071228.131917.4100.txt
JVMDG303: JVM Requesting Java core file
JVMDG304: Java core file written to E:\IBM\WebSphereND\AppServer\profiles\AppSrv01\javacore.20071228.131924.4100.txt
JVMDG215: Dump Handler has Processed Dump Signal 21.
Locating the Java heapdump
The heapdump file location will be reported to stderr (usually the command window) by the JVM. If you set IBM_HEAPDUMPDIR, this directory should be used. Typically the file name will look something like this:
heapdump.YYYYMMDD.HHMMSS.PID.phd
YYYMMDD is the date that the file was produced, HHMMSS is the system time, and PID is the Process ID of the JVM. The file extension will be PHD for a portable heapdump, and TXT for a text heapdump. As an example, the file name might be:
heapdump.20071224.141948.3696.phd
From the IBM Java SDK version 1.6.0, the heapdump files (PHD and TXT) have an extra component in the file name, as follows:
heapdump.YYYYMMDD.HHMMSS.PID.XXXX.txt
where the XXXX appears to be a simple counter. This seems to allow up to 999 heapdump files within the same second. We would not recommend that you do that! As an example, the file name might be:
heapdump.20080104.103747.3628.0003.txt
Note that with any IBM JVM, you may also find a similarly named Java Core file, such as:
javacore.YYYYMMDD.HHMMSS.PID.[count].txt
JProbe does not import (and does not require) this core file. If you find only the javacore file, check your environment variables to be sure they are properly set to generate the heap dump.
Importing and analyzing the Java heapdump with JProbe
Exact steps depend on your version of JProbe. Please consult the appropriate document:
JProbe 7.0: http://jprobe.inside.quest.com/entry.jspa?externalID=2022&categoryID=127
JProbe 8.0: http://jprobe.inside.quest.com/entry.jspa?externalID=2023&categoryID=127
