Creating a Java heap dump

Solution Verified - Updated

Environment

  • Java
    • Oracle (Sun) JDK
    • OpenJDK
    • HP-UX JDK
    • JRockit
  • Red Hat JBoss Enterprise Application Platform (JBoss EAP)

Issue

  • Weird behavior and out of memory issues.
  • How do I create a Java heap dump?
  • Any special considerations for clustering environments?
  • Configure JBoss EAP create Heap dump automatically
  • Generate heap Dump after process is killed
  • Specify location of file output

Resolution

JDK / Version

OpenJDK / Oracle JDK 11

  1. HeapDumpOnOutOfMemoryError
  2. jcmd
  3. jmap - Java Process
  4. jmap - Core File
  5. JConsole

OpenJDK / Oracle JDK 1.8

  1. HeapDumpOnOutOfMemoryError
  2. jcmd
  3. jmap - Java Process
  4. jmap - Core File
  5. jmap - OpenShift
  6. JConsole
  7. JBoss JMX Console

OpenJDK / Oracle JDK 1.7

  1. HeapDumpOnOutOfMemoryError
  2. jmap - Java Process
  3. jmap - Core File
  4. JConsole
  5. JBoss JMX Console

OpenJDK / Oracle JDK 1.6

  1. HeapDumpOnOutOfMemoryError
  2. jmap - Java Process
  3. jmap - Core File
  4. JConsole
  5. JBoss JMX Console

OpenJDK / Oracle JDK 1.5

  1. HeapDumpOnOutOfMemoryError
  2. jmap - Java Process
  3. jmap - Core File
  4. HeapDumpOnCtrlBreak
  5. runhprof

IBM

  1. OutOfMemoryError

HP

  1. HeapDumpOnOutOfMemoryError

JRockit

  1. jrcmd

Reference

-XX:+HeapDumpOnOutOfMemoryError

   OpenJDK
   Sun/Oracle JDK 1.4.2\_12 (except with throughput collector -XX:+UseParallelGC, which requires 1.4.2\_15)
   Sun/Oracle JDK 1.5.0_07
   Sun/Oracle JDK 1.6.0 and all later ones.
   HP-UX JDK 1.4.2_11
   JRockit R28 and up

Notes:

  • Produces dumps in hprof format, a binary, platform-independent format.

  • By default the heap dump is created in the directory defined by the user.dir environment variable and named java_pid<pid>.hprof, where <pid> is the  Java process id. For JBoss, check boot.log to see the value of user.dir (e.g. $JBOSS_HOME/bin).

  • Use the -XX:HeapDumpPath option to specify a different location (e.g. -XX:HeapDumpPath=/mypath/). If you specify a directory Java will write it there using the default file name, including the process id. If you specify a file name (e.g. -XX:HeapDumpPath=/mypath/myheapdump.hprof) heap dumps will not overwrite each other. Only the initial file will be written. Subsequent heap dumps will fail due to the existing file. Unless disk space is a concern, you typically do not want to lose data.

  • This option does not impact performance (until the heap is actually written out); it is simply a flag to indicate that a heap dump should be generated when the first thread throws OutOfMemoryError.

  • It is typically a best practice to use this JVM option, as it provides critical information in case of a memory error.

  • For JBoss EAP, see Configuring JVM SETTINGS for instructions on setting command line parameters. This covers standard, clustered, and domain mode configuration. You can set the same command line parameters as you would for an Java-based application.

  • See Java heap dump not created on OutOfMemoryError for details on why a heap dump may not be created even when the jvm parameter -XX:+HeapDumpOnOutOfMemoryError is present/

  • To verify a thread dump was created by -XX:+HeapDumpOnOutOfMemoryError, look for a java.lang.OutOfMemoryError object in the heap (SELECT * FROM java.lang.OutOfMemoryError) and check that the thread that references it is calling the OutOfMemoryError.. Or look through the produced .threads file and grep for the OutOfMemoryError to see that a thread is calling OutOfMemoryError..

-XX:+HeapDumpOnCtrlBreak

Effective from Sun JDK 1.5.0_14, but note HeapDumpOnCtrlBreak it does not work in JDK 1.6 and beyond.

  • Produces dumps in hprof format, a binary, platform-independent format.

  • kill -3 JAVA_PID (or Ctrl-Break on Windows) will cause the heap dump to be created (in addition to a stack trace). For Windows, you can use the Content from www.latenighthacking.com is not included.SendSignal utility to send the Ctrl-Break signal from the command line. See the following document for details using SendSignal: How do I generate a Java thread dump on Windows?.

  • The heap dump will be created in the directory defined by the user.dir environment  variable and named java_pid<jboss_pid>.hprof.<date>.<time>.  For JBoss, check boot.log to see the value of user.dir (e.g. $JBOSS_HOME/bin).

jmap - java process

Heap dump is created in the directory where the jmap command is issued. If using RHEL's OpenJDK, ensure the corresponding devel package is installed for jmap (java-1.6.0-openjdk-devel or java-1.7.0-openjdk-devel).

  • Sun JDK 1.5: (excluding Windows or Linux Itanium)

    • jmap -heap:format=b <JAVA_PID>

  • Sun JDK 1.5 64-bit: (excluding Windows or Linux Itanium)

    • jmap -J-d64 -heap:format=b <JAVA_PID>

Notes:

  • Note that you need to make sure to execute jmap command from same user to the java process. Please see this article for more details.

  • Heap dump is created in the directory where the jmap command is issued.

  • Heap dump file is named heap.bin, or you can name it.

  • This syntax also works on Sun JDK 1.6; however, the heap dump will not include some advanced 1.6 features (e.g. stack traces for stack roots) and will run slower than the 1.6 syntax. Therefore, do not use the 1.5 syntax on a 1.6 JVM.

  • Sun JDK 1.6, OpenJDK:

    • jmap -dump:format=b,file=heap.hprof JAVA_PID

  • Sun JDK 1.6, OpenJDK 64-bit

    • jmap -J-d64 -dump:format=b,file=heap.hprof JAVA_PID

  • Sun JDK 1.6 (Windows):

    • jmap -dump:format=b,file=heap.hprof JAVA_PID

Notes:

  • Heap dump is created in the directory where the jmap command is issued.
  • Heap dump file is named according to file attribute.
  • Available on Windows, but not on Linux Itanium.
  • The -J option does not work on Windows.
  • Heap dump file generated is only accessible to the user who is the JBoss process owner.
  • If you more quickly want some more human readable text file about heap use, you could use below jmap command to print a histogram instead of the full binary heap dump. This just lists class names in order by the total number of bytes they retain with the number of instances of that object. That's human readable text for an easy way to see top consuming class currently, but note it doesn't allow any more advanced review often required that can only be done in a heap dump (like identify what references keep objects in heap, comparing sizes of individual instances, reviewing any values of any fields, reviewing any thread states and stacks, etc.).
$ jmap -histo $PID

jmap - core file

jmap blocks when creating the heap dump, and with large heaps, this can take a very long time.
In these cases it is often much faster to get a core and then run jmap to extract a heap dump from the core.
It is typically best to create the heap dump on the same box where the core was created to avoid environment differences.

OpenJDK 11: 

$JAVA_HOME/bin/jhsdb jmap --binaryheap --dumpfile heap.hprof --exe $JAVA_HOME/bin/java --core core.pid

OpenJDK 8, 1.7, 1.6

jmap -J-d64 -dump:format=b,file=heap.hprof JAVA_HOME/bin/java COREFILE > heap.out 2>&1 (64-bit Linux)
    
jmap -dump:format=b,file=heap.hprof JAVA_HOME/bin/java COREFILE > heap.out 2>&1 (Windows, 32-bit)

jmap -dump:format=b,file=heap.hprof JAVA_HOME/bin/java COREFILE > heap.out 2>&1 (32-bit)

Notes:

  • Be sure to specify the path to the java executable relevant to the core. grep the core to confirm the expected path. For example:
    • strings core.pid | grep java
  • Available on Windows, but not on Linux Itanium.
  • The -J option does not work on Windows.

Sun JDK 1.5:

jmap -J-d64 -heap:format=b JAVA_HOME/bin/java COREFILE > heap.hprof 2>&1 (64-bit)

jmap -heap:format=b JAVA_HOME/bin/java COREFILE > heap.hprof 2>&1 (32-bit)

Notes:

  • Be sure to specify the path to the java executable relevant to the core.
  • Not available on Windows or Linux Itanium. For Windows on 1.5, consider -XX:+HeapDumpOnCtrlBreak or third party tools such as Eclipse Memory Analyzer Tool (MAT) for capturing a heap dump.
  • This  syntax also works on Sun JDK 1.6; however, the heap dump will not  include some advanced 1.6 features (e.g. stack traces for stack roots)  and will run slower than the 1.6 syntax. Therefore, do not use the 1.5  syntax on a 1.6 JVM.

jmap - Windows Service

jmap - OpenShift

JRockit R28 and up

jrcmd <JAVA_PID> hprofdump filename=abc.hprof

Notes:

IBM JDK

A portable heap dump (phd) format heap dump is created in the temp directory (e.g. /tmp/) when OutOfMemoryError is thrown.

JConsole

Starting with Sun JDK 1.6 you can Content from docs.oracle.com is not included.get a heap dump from JConsole:

  1. Go to MBeans/com.sun.management/HotSpotDiagnostic/Operations.
  2. Enter "heap.hprof" in the p0 textbox and "true" in the p1 textbox.
  3. Click the dumpHeap button.

The heap dump will be created in the directory defined by the user.dir environment  variable and named heap.hprof.  For JBoss,  check boot.log to see the value of user.dir (e.g. $JBOSS_HOME/bin).

runhprof

  • Sun JDK 1.3, 1.4 (deprecated in Sun JDK 1.5):

  • Enabled with the following JVM option:

          -Xrunhprof:heap=dump,file=dump.hprof,format=b

Notes:

  • kill -3 JAVA_PID (or Ctrl-Break on Windows) will cause the heap dump to be created (in addition to a stack trace). You can also use the Content from www.latenighthacking.com is not included.SendSignal utility on Windows to send the Ctrl-Break from the command line.

  • Produces dumps in hprof format, a binary, platform-independent format.

  • dump.hprof.TMP and dump.hprof placeholder files are created in the directory defined by the user.dir environment  variable and written to when kill -3 JBOSS_PID or Ctrl+Break is executed.  For JBoss,  check boot.log to see the value of user.dir (e.g. $JBOSS_HOME/bin).

  • Taking more than one heap dump will cause the following error and crash the JVM: "HPROF ERROR: Mis-match on instance size in instance dump" due to the following bug:
    Content from bugs.sun.com is not included.Content from bugs.sun.com is not included.http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6379450

  • Run java -Xrunhprof:help for configuration options.

JBoss JMX Console

  1. Open JBoss EAP 4.x/5.x JMX console, and go to the "HotSpotDiagnostic" MBean under com.sun.management.
  2. For the "dumpHeap" operation, enter "heap.hprof" for the first parameter and "true" for the second parameter.
  3. Press Invoke

It will create a heap dump called "heap.hprof" in JBoss' working directory (probably $JBOSS_HOME/bin). Alternatively, you can specify a full path for the first parameter.

jcmd

Valid for Oracle JDK and OpenJDK. This is Oracle's preferred method since JDK 8 because it is faster than jmap in some scenarios. Note that, as the help says the following, this initiates a full GC by default unless the '-all' option is specified. 

GC.heap_dump
Generate a HPROF format dump of the Java heap.

Impact: High: Depends on Java heap size and content. Request a full GC unless the '-all' option is specified.

Permission: java.lang.management.ManagementPermission(monitor)

Syntax : GC.heap_dump [options] <filename>

Arguments:
	filename :  Name of the dump file (STRING, no default value)

Options: (options must be specified using the <key> or <key>=<value> syntax)
	-all : [optional] Dump all objects, including unreachable objects (BOOLEAN, false)

Example:

  • Generate heap dump preceded by full GC
$ jcmd <JAVA_PID> GC.heap_dump /path/to/heapdump.hprof
  • Generate a heap dump not preceded by full GC
$ jcmd <JAVA_PID> GC.heap_dump -all=true  /path/to/heapdump.hprof

Using just the file name, the heap dump file will be created on the directory which was used to start the application.

SBR
Product(s)
Components
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.