How to generate a JVM heap memory dump?

The analysis of some problems requires having a heap memory dump of the JVM. This document explains how to generate such a thread dump.

On demand

Using the tnd-dump-heap script

This script is available starting with release 20160229 which is the first release with an installer including an embedded JRE. For older releases, use the java tools directly as described below.

Execute the script <node dir>/bin/tnd-dump-heap.bat (Windows) or <node dir>/bin/tnd-dump-heap.sh (Linux).

If successful, the dump is written in a timestamped file in the <node dir>/var directory.

Example:

> <node dir>/bin/tnd-dump-heap.sh
 
18380:
Heap dump file created
heap dump generated in file <node dir>/var/dump_heap.20160225_162821.bin

Using the java tools directly

The generation of the heap dump is a two-step process:

The following steps require the use of a JDK or a Server JRE. If you only installed a JRE to run your node, you will not have access to the following tools.

1. Identify the PID of the java process

For information, see  How to identify the node process ID?

2. Generate the heap dump

Open a shell with the same user that is running the JVM to avoid OS security problems. Depending on whether jmap or jcmd is available, execute one the following command, where $JAVA_HOME is the one that was used to launch the JVM to analyze (replace 32088 with the PID you found in the previous step):

$JAVA_HOME/bin/jmap -dump:format=b,file=heap.bin 32088

or

$JAVA_HOME/bin/jcmd 32088 GC.heap_dump heap.bin

The heap dump is written in heap.bin file in the current working directory.

Automatically when an OutOfMemoryError is encountered

Edit the conf/jvm.conf file in order to add the -XX:+ HeapDumpOnOutOfMemoryError parameter. When an out of memory error is encountered, a heap memory dump is automatically created.


Related Links