KB-1176 How to generate a Java heap dump

Purpose

Appian Technical Support might ask you to provide them with Java heap dumps to troubleshoot memory leaks, performance issues, etc. There are different ways of generating this file. This article describes the most common way of generating a heap dump. Please note that these commands should be run on the application server machine when collecting a heap dump of the application server's Java process.

Instructions

  1. For Windows, open Command Prompt as administrator (right-click Windows Command Processor and select Run as administrator). For Linux, open a new Terminal session.
  2. Navigate to <JAVA_HOME>/bin.
  3. Run the following command (replace <APPIAN_HOME> with the path to <APPIAN_HOME> and <PID of Java Process> with the ID of the Java process):
    jmap -dump:format=b,file="<APPIAN_HOME>/logs/heapdump.hprof" <PID of Java Process>

The jmap command will generate a file named heapdump.hprof under <APPIAN_HOME>/logs.

If Technical Support requests that you capture a heap dump without running Java Garbage Collection, use the following command:

jmap -dump:live,format=b,file="<APPIAN_HOME>/logs/heapdump.hprof" <PID of Java Process>

To determine the ID of the Java process, run ps -ef | grep java in Linux or open Windows Task Manager and go to the Processes tab in Windows.

Note: the raw heap dump file may contain sensitive information from your Appian environment. For this reason, Appian Technical Support will ask you to run heap dump analysis on the raw output to generate an analysis file that does not contain any sensitive data. There is a range of software that can perform heap dump analysis. The steps for performing this analysis using the Java Memory Analyzer are as follows:

  1. Download the correct Java Memory Analyzer for your system from here.
  2. Unzip MemoryAnalyzer-*.zip into <MEMORY_ANALYZER_HOME>
  3. For Windows, open Command Prompt as administrator (right-click Windows Command Processor and select Run as administrator). For Linux, open a new Terminal session.
  4. Navigate to <MEMORY_ANALYZER_HOME>/mat.
  5. Run the analysis command (replace <APPIAN_HOME> with the path to <APPIAN_HOME>):
./ParseHeapDump.sh|bat "<APPIAN_HOME>/logs/heapdump.hprof" org.eclipse.mat.api:suspects

The analysis file will then be available at <APPIAN_HOME>/logs/Leak_Suspects.zip

For scenarios where there's no leak but only high heap usage that eventually goes down, the leak suspects report will show a considerably smaller size of the heap when compared to the original heap dump size. This is because the parsing removes unreachable objects simulating what garbage collection will eventually do.

If you're analyzing something that is not a leak, then you don't want the unreachable objects to be removed because you need to know what needs to be optimized that's consuming too much heap.

To get that information in the report add the -keep_unreachable_objects flag:

./ParseHeapDump.sh|bat -keep_unreachable_objects "<APPIAN_HOME>/logs/heapdump.hprof" org.eclipse.mat.api:suspects

Affected Versions

This article applies to all versions of Appian.

Last Reviewed: March 2017

Related
Recommended