How to generate a heap dump?

A heap dump is a snapshot of the memory of a Java process at a certain point in time. There are different formats for persisting this data, and depending on the format it may contain different pieces of information, but in general the snapshot contains information about the Java objects and classes in the heap at the moment the snapshot was triggered. Usually a full GC is triggered before the heap dump is written so it contains information about the remaining objects.

To generate a heap dump the first part is to obtain the process id (or PID). There are multiple methods to obtain the PID:

NOTE: You must run the following commands as the user that Jenkins is running as. Usually this user is 'jenkins.' No other user, including root, will be able to run the command successfully.

After obtaining the process id ($PID), the next step is to generate the heap dump using jcmd:

jcmd is the preferred method for generating a heap dump per Oracle Documentation

If you are experiencing a problem using jcmd please use the alternative jmap method: jmap -dump:format=b,file=$FILENAME.hprof $PID - From Unix Terminal or Windows Powershell

NOTE: The JVM will need to perform a full garbage collection cycle before it can generate a heap dump, in order to free as many unused objects as possible first. Jenkins will be paused/unavailable during this time. For very large heap sizes, the full GC could be slow, so it’s important to realize that getting a heap dump may impact users of the application.

Generating heap dumps periodically during an OOM issue is beneficial, particularly after a service restart to baseline the instance, and subsequently later to show the memory growth over a period of time. Attach the output generated from these commands to a CloudBees support ticket, so we can help diagnose further.

Heap Dumps can be quite large in size, therefore the split utility comes in handy here, as our upload site supports 10GB uploads, but can be difficult depending on your internet connection. Thus, use the split linux utility to split the generated heapdump file into 2GB segments for ease of upload to your support ticket and our team will cat them together once received. or Windows Cmd

To concatenate files after splitting:

Sometimes you will face some problems while collecting the heap dump and will get errors such as:

In some cases, enabling the -F option is extremely slow, especially for large heaps. The error mentioned above is generally related to permissions issues with the user taking the heap dump. To prevent this kind of errors, the user taking the heap dump should be the same user who is running the Java process. And sometimes you will even need to call the user explicitly running the command using the following syntax:

If you are using CentOS 7 or higher, you have to take into consideration that SELinux will stop Jmap from writing heapdumps unless the directory where the dump is going to be generated (runtime user owned). The easiest way to proceed is to disable temporarily SELinux.