Different Ways to Capture Java Heap Dumps

Head dump is a snapshot of all the objects that are in memory in the JVM at a certain moment. They are very useful to troubleshoot memory-leak problems and optimize memory usage in Java applications. Head dumps are usually stored in Binary format ‘hprof’ files. We can open and analyze these files using tolls like ‘jhat’ or ‘JVisualVM’. Also, for Eclipse users it’s very common to use MAT. Now we will go through multiple tools and approaches to generate a head hump, and we will show the main difference between them.

The JDK comes with several tools to capture head dumps in different ways. All these tools are located under the bin folder inside the JDK home directory. Therefore, we can start them from the command line a long as this directory is included in the system path.

In the next steps, we will see how to use these tools in order to capture head dumps.

Methods:

1. jmap
2. jcmd
3. JVisualVM
4. Capture Head Dump Automatically
5. JMX

Let us discuss each of the above-listed methods in detail to get a better understanding of them. 

Method 1: jmap

jmap is a tool to print statistics about memory in a running JVM. We can use it for local or remote processes. To capture a head dump using jmap we need to use the dump option:

 jmap -dump:[live],format=b,file=<file-path> <pid>

Along with that option, we should specify several parameters:

• live: if set it only prints objects which have active references and discards the ones that are ready to be garbage collected. This parameter is optional
• format=b: specifies that the dump file will be in binary format. If not set the result is the same
• file: the file where the dump will be written to
• pid: id of the Java process

Note: We can easily get the PID of a Java process by using the ‘jps’ command. Keep in mind that jmap was introduced n the JDK as an experimental tool, and it’s unsupported. Therefore, in some cases, it may be preferable to use other tools instead.

Example

jmap -dump:live,format=b,file=/tmp/dump.hprof 12587

Method 2: jcmd

‘jcmd’ is a very complete tool that works by sending command requests to the JVM. We have to use it in the same machine where the Java process is running. One of its many commands is the GC.heap-dump. We can use it to get a heap dump just by specifying the pid of the process and the output file path:

 jcmd <pid> GC.head_dump <file-path>

We can execute it with the same parameter that we used before:

jcmd 12587  GC.head_dump  /tmp/dump.hprof

As with the jmap, the dump generated is in binary format.

Method 3: JVisualVM

JVisualVM is a tool with a graphical user interface that lets us monitor troubleshoot, and profile Java applications. The GUI is simple but very intuitive and easy to use. One of its many options allows us to capture a head dump. If we right-click on a Java process and select the Head Dump” option, the tool will create a heap dump and open it in a new tab:

As we notice above that we can find the path of the file created in the “Basic Info” section. Starting from JDK9, VISUAL VM is not included in the Oracle JDK and Open JDK distributions. Therefore, if we are using Java 9 or newer versions, we can get the JVisualVM from the Visual VM open source project site.

Method 4: Capture Head Dump Automatically

All the tools that we have shown above are intended to capture head dumps manually at a specific time. In some cases, we want to get a heap dump when a java.lang.OutOfMemoryError occurs so it helps us to investigate the error:

For these cases, Java provides the HeadDumpOnOutOfMemoryError command-line option that generates a heap dump when a java.lang.OutOfMemoryError is thrown:

java -XX:+HeadDumpOnOutOfMemoryError

By default, it stores the dump in a java_pid<pid>.hprof file in the directory where we are running the application. If we want to specify another file or directory we can set it in the HeadDumpPath option:

java -XX:+HeadDumpOnOutOfMemoryError -XX:HeapDumpPath=<file-or-dir-path>

When our applications run out of memory using this option, we will be able to see in the logs the created file that contains the heap dump:

java.lang.OutOfMemoryError: Requested array size exceeds VM limit
During heap to java_pid12587.hprof...
  Exception in thread "main" Head dump file created [4744371 bytes in 0.029 secs]
  java.lang.OutOfMemoryError: Requested array size exceeds VM limit 
  at com.baeldung.heapdump.App.main(App.java:7)

In this example above it was written to the java_pid2587.hprof file. As we can see, this option is very useful and there is no overhead when running an application with this option. Therefore, it’s highly recommended to use this option always, especially in production. Finally, this option can also be specified at runtime by using the HotSpotDiagnostic MBean. To do so, we can use JConsole and set the HeapDumpOnOutOfMemoryError VM option to true:

Method 5: JMX

The last approach that we will cover in this article is using JMX. We will use the HotSpotDiagnostic MBean that we briefly introduced in the previous section. This MBean provides a dumpHeap method that accepts 2 parameters:

• outputFile: the path of the file for the dump. The file should have the hprof extension
• live: if set to true it dumps only  the active objects in memory, as we have seen jmap before

Now here are 2 ways to invoke this method in order to capture a head dump:

The easiest way to use the HotSpotDiagnostic MBean is using a JMX client such as JConsole. If we open JConsole and connect to a running Java process, we can navigate to the MBeans tab and find the HotSpotDiagnostic under com.sun.management.  In these operations we can find the dumpHead method that we have described before:

As shown, we just need to introduce the parameters outputFile and live into the p0 and p1 text fields in order to perform the dumpHeap operation.

Implementation: Way to Capture Heap dump

The other way to use the HotSpotDiagnostic MBean is by invoking it programmatically from Java code. To do so, we need to get an MBeanServer instance in order to get an MBean that is registered in the application. After that, we simply need to get an instance of a HotSpotDiagnosticMXBean and calls it dumpHeap method.

public static void dumpHeap(String filePath, boolean live) throws IOException {
MBeanServer server = ManagementFactory.getPlatformMBeanServer();
HotSpotDiagnosticMXBean mxBean = ManagementFactory.newPlatformMXBeanProxy
  (server, "com.sun.management:type=HotSpotDiagnos
  tic",
HotSpotDiagnosticMXBean.class);
mxBean.dumpHeap(filePath, live);
}

Notice that a hprof file can not be overwritten. Therefore, we should take this into account when creating an application that prints heap dumps. If we fail to do so we will get an exception:

Exception in thread "main" java.io.IOException: File exists 
at sun.management.HotSpotDianostic.dumpHeap0(Native Method) at 
sun.management.HotSpotDiagnostic.dumpHeap(HotSpotDiagnostic.java:60)

Conclusion: The last rule that we must always remember is to use- the HeapDumpOnOutOfMemoryError option always when running Java applications.