How to generate a heap dump and class histogram

Created by Steve Place, Modified on Tue, Mar 11 at 12:07 PM by Steve Place

A heap dump provides a snapshot of memory usage at a specific moment, allowing investigation into memory leaks or inefficient memory usage. A class histogram provides a summary of Java object instances currently allocated. You usually only need to generate one for us to be able to troubleshoot your problem.

How to generate a heap dump

Get the process ID for Stardog with:

ps aux | grep stardog

Then get the heap dump with:

jmap -dump:format=b,file=heapdump.hprof [PID]

This generates a file named heapdump.hprof.

Note this requires jmap to be installed. We recommend installing this, as it helps manage any Java system in production.

If you're running Stardog in a container as non-root, you can install the full JDK (and by extension, jmap) by running:

docker exec --user root [theRunningContainerName] apt-get install -y openjdk-11-jdk-headless

Heap dumps can be quite large, so see this article on how to send large files to Support.

Heap Dump on OOM

If you're running Stardog 9.2.0 or later, heap dumps are enabled by default. If you're using an earlier version or have them disabled, you can enable them by adding -XX:+HeapDumpOnOutOfMemoryError to your STARDOG_SERVER_JAVA_ARGS. The file produced will be something like java_pidXXXXXXX.hprof (where XXXXXXX is some string of numbers) and will exist in your Stardog home directory.

How to generate a class histogram

To generate a class histogram, you need to add -XX:+PrintClassHistogram to your STARDOG_SERVER_JAVA_ARGS. You'll need to restart your Stardog server for this change to take effect.

Get the process ID as above and send a SIGQUIT signal to the Stardog process to generate a class histogram:

kill -QUIT [PID]