Introduction

The heap is created at the start of a Java Virtual Machine (JVM) and is an area of memory where Java objects reside.

A heap dump (or memory dump) is a snapshot of all java objects in the JVM at a certain point in time. 

Generating memory dumps is helpful when trying to diagnose potential memory leaks, OutOfMemoryError exceptions, issues with Garbage Collection, or optimizing memory usage. 

Background

The JVM allocates memory as it runs and Garbage Collection deletes unneeded or unreferenced objects by reclaiming memory from the heap to free up space. 

The heap is not the only memory that the JVM will use - Java methods, thread stacks, native handlers, internal data structures, etc. are allocated in memory separate from the heap. This is why the size of the heap is not the same size as the memory displayed in the Task Manager (or ps/pmap commands for Linux and Activity Monitor for Mac).

The heap is only a part of the total allocated memory to a JVM.

The current size of the heap can be found most easily on the Gateway webpage > Status > Performance.

Prerequisites

In order to generate a heap dump there are a few requirements:

• Java JDK installed on the server
  • The JDK can be downloaded from Oracle's website after signing in. https://www.oracle.com/java/technologies/downloads/
  • Java 11 for Ignition 8+ and Java 8 for Ignition 7.9
• Administrator privileges in order to run Jmap command.
• A folder to write the dump files to.
• Enough storage available on the disk drive.
  • A heap dump is a snapshot of the heap at a specific time so the file generated will be roughly the same size as the heap. This could be anywhere from 1GB up to 20GB+

Generating a heap dump can take some time to complete and can cause the JVM to appear hung. The larger the heap, the longer the pause. If the pause is long enough (default 30 seconds) then the JVM will restart - aborting the heap dump. To avoid this, it is recommended to set the timeout parameter in the ignition.conf file to increase this timeout threshold.  Place the wrapper.ping.timeout parameter under the Wrapper Java Properties section after the other time out parameters. 

A Gateway service restart is required for Ignition to load the changes made to the ignition.conf file. After the restart, it would be a good idea to do a test run of generating a heap dump to practice the process and verify everything happens as expected. This will be a test heap dump with relatively little memory.

Process

It's important to note that the process for generating a heap dump is much the same on different operating systems, the differences are leading up to the actual heap dump command. 

In the following examples, let's assume we're running Ignition 8.1 and we will be using the jmap command. 

For Windows

The JDK11 location is C:\Program Files\Java\jdk-11.0.11 and we've created a folder to save our heap dumps in C:\Mem_Dumps\

1. Launch the Command Prompt as an Administrator
2. Get Ignition's PID (Process ID):
   • Run the netstat command netstat -anon | findstr <port> and look for the Gateway port in the second column - that row will have the PID in the last column. Here we are using the default port of 8088.
     
3. Generate a heap dump:
   • Navigate to the JDK install directory and into the bin folder using the cd command.
   • Run the Jmap command jmap -dump:file=C:\Mem_Dumps\dump1.bin <PID>
     

For Linux

The JDK11 location is /usr/bin/ and we've created a folder to save our heap dumps in /home/paul/Documents/Mem_Dumps/

Note that the JDK can also be installed by using the command: sudo apt install default-jdk

1. Launch the Terminal
2. Get Ignition's PID (Process ID):
   • Run the command jps -m and look for the first number in the line for WrapperSimpleApp
     
3. Generate a heap dump:
   • Run the jmap command jmap -dump:file=/home/paul/Documents/Mem_Dumps/dump1.bin <PID>
     

Note:

It's also possible to generate a heap dump using the jcmd command as well. That would look something like: jcmd <pid> GC.heap_dump <file-path>

Post Process

After generating a good heap dump it is recommended to remove or comment out the wrapper.ping.timeout parameter so that the JVM can automatically restart if it becomes hung - a Gateway restart will be required.