This article will teach you what is the usage of the HeapDumpOnOutOfMemoryError JVM parameter and how to configure it on an application server such as JBoss EAP or WildFly.
HeapDumpOnOutOfMemoryError made simple
The JVM parameter “-XX:+HeapDumpOnOutOfMemoryError” captures OutOfMemoryError instances that occur due to memory exhaustion in the Java heap space. When the Java Virtual Machine (JVM) encounters an OutOfMemoryError related to the heap space, it automatically generates a heap dump file.
This parameter needs to apply when you start the JVM, therefore you need to include it in your start up options.
For example, you can add it to your IDE as JVM Option:
On the other hand, if you are starting your Java process in a script you need to apply the JVM parameter in the start script. For example, if you are running WildFly in standalone mode, then you can include it into the standalone.conf configuration file:
JAVA_OPTS="$JAVA_OPTS -XX:+HeapDumpOnOutOfMemoryError"
Check this tutorial to learn how to set this parameter for Domain Mode: Configuring JVM Settings in a WildFly / JBoss Domain
Out of the box, the HeapDump is generated in the current working directory of the Java process. Therefore, if you are running WildFly or JBoss the current directory of the process is the $JBOSS_HOME/bin folder. If you want to place it on a different folder, you need to include also the parameter HeapDumpPath as in this example:
JAVA_OPTS="$JAVA_OPTS -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/tmp/dumps"
It is worth mentioning that there is no overhead in running with this option, and so it can be useful for production systems where OutOfMemoryError takes a long time to surface.
The heap dump is in HPROF binary format, and so you can analyze it using any tools that can import this format. For example, the jhat tool can be used to do rudimentary analysis of the dump.
Which OutOfMemory error you can capture with this parameter
It’s important to note that the “-XX:+HeapDumpOnOutOfMemoryError” parameter only captures OutOfMemoryError instances related to heap space issues such as:
- java.lang.OutOfMemoryError: Java heap space: This error occurs when the JVM cannot allocate more memory to the Java heap to accommodate new objects and the garbage collector is unable to free up enough space. It indicates that the application is using more memory than what is available for the heap.
- java.lang.OutOfMemoryError: GC overhead limit exceeded: This error happens when the JVM spends an excessive amount of time doing garbage collection, but only a small amount of memory is being reclaimed. This indicates that the garbage collector is struggling to free up memory, and the application might need optimization or more available heap space.
- java.lang.OutOfMemoryError: Requested array size exceeds VM limit: This error occurs when the JVM cannot allocate memory for a new array because the requested size exceeds the maximum limit set by the VM. It is generally related to large array allocations.
Other types of errors, such as StackOverflowError or OutOfMemoryError related to native memory, will not trigger heap dump generation with this parameter.
