How to Create a Heap Dump for Your Java Application

The heap (in a JVM) is the place where a JVM keeps all its runtime objects. The JVM creates a dedicated space for the heap at the JVM startup, which can be controlled via the JVM option -Xms<size> eg: -Xms100m (this will allocate 100MBs for the heap). The JVM is capable of increasing and decreasing the size of the heap [1] based on the demand, and the JVM has another option which allows to set a max size for the heap: -Xmx<size>, eg: -Xmx6g (this allows the heap to grow up to 6GBs).

The JVM automatically performs Garbage Collection (GC) when it detects that the JVM is about to reach the max heap size. But the GC can only clean the objects which are eligible for GC. If the JVM can't allocate required memory even after GC, JVM will crash with "Exception in thread "main" java.lang.OutOfMemoryError: Java heap space".

If your Java application in production crashes due to some issue like this, you can't just ignore the incident and restart your application. You have to analyze the what caused the JVM to crash, and take the necessary actions to avoid it happening again. This is where the JVM heap dump comes into play.

If JVM heap dumps are by default disabled, you have to enable heap dumps explicitly by providing the following JVM option: -XX:+HeapDumpOnOutOfMemoryError.

The below sample code, tries to create a multiple, large arrays of chars, and keep the references in list. Which cause those large arrays ineligible for garbage collection.

package com.test;

import java.util.ArrayList;
import java.util.List;

public class TestClass {
    public static void main(String[] args) {
        List<Object> list = new ArrayList<Object>();
        for (int i = 0; i < 1000; i++) {
            list.add(new char[1000000]);
        }
    }
}

If you run the above code with the following command lines:

1. java -XX:+HeapDumpOnOutOfMemoryError -Xms10m -Xmx3g com.test.TestClass

Result: Program runs and exits without any error. The heap size starts from 10MB and then grows as needed. Above program needs memory less than 3GB. So, it completes without any error.

2. java -XX:+HeapDumpOnOutOfMemoryError -Xms10m -Xmx1g com.test.TestClass

Result: JVM crashes with OOM.

If we change the above code a bit to remove the char array from the list, after adding to the list, this would be the result:

package com.test;

import java.util.ArrayList;
import java.util.List;

public class TestClass {
    public static void main(String[] args) {
        List<Object> list = new ArrayList<Object>();
        for (int i = 0; i < 1000; i++) {
            list.add(new char[1000000]);
            list.remove(0);
        }
    }
}

3. java -XX:+HeapDumpOnOutOfMemoryError -Xms10m -Xmx10m com.test.TestClass

Result: This code runs without any issue even with a heap of 10MBs.

NOTE:

1. There is no impact to your application if you enable the heap dump in the JVM. So, it is better to always enable -XX:+HeapDumpOnOutOfMemoryError in your applications.

2. You can create a heap dump of a running Java application with the use of 'jmap'. jmap comes with the JDK. Creating a heap dump of a running application cause the application to halt everything for a while. So, it is not recommended to use in production system. (unless there is an extreme situation).
   eg: jmap -dump:format=b,file=test-dump.hprof [PID]

3. Above sample codes are just for understanding the concept. 

[1] https://docs.oracle.com/cd/E13150_01/jrockit_jvm/jrockit/geninfo/diagnos/garbage_collect.html