Issue

The Semarchy Support Team may request a Thread Dump or Heap Dump when investigating Runtime performance issues, memory consumption problems, deadlocks, hangs, or unexpected behavior.

These diagnostic files provide valuable information about the state of the JVM and can significantly accelerate troubleshooting.


Prerequisites

To generate dumps, one of the following tools is required:

  • A supported JDK installation (Java 17, Java 21, or the Java version supported by your xDI release).
  • VisualVM.
  • JDK diagnostic tools such as jcmd, jstack, and jmap.

Important: Some Runtime configurations disable the JVM Attach API for security reasons. If dump generation fails with attach-related errors, review the Runtime JVM startup options and verify whether the JVM attach mechanism has been disabled.

Method 1: Using VisualVM

  1. Install VisualVM from:
  2. Start VisualVM.
  3. Select the target xDI Runtime process.
  4. To generate a Heap Dump:
    • Open the Monitor tab.
    • Select Heap Dump.
  5. To generate a Thread Dump:
    • Open the Threads tab.
    • Select Thread Dump.



Method 2: Using Command Line Tools

First identify the Runtime process:

jps -l

or

jcmd

Generate a Thread Dump:

jcmd <PID> Thread.print > thread-dump.txt

Alternatively:

jstack <PID> > thread-dump.txt

Generate a Heap Dump:

jcmd <PID> GC.heap_dump heap-dump.hprof

Alternatively:

jmap -dump:live,format=b,file=heap-dump.hprof <PID>

Recommendations

  • Generate multiple Thread Dumps (for example 3 dumps separated by 30 seconds) when investigating hangs or performance issues.
  • Compress Heap Dumps before uploading them to Support, as they can be several gigabytes in size.
  • Generate dumps during the issue occurrence whenever possible.
  • Provide Runtime logs together with the dump files.

Tip: The jcmd utility is the preferred diagnostic tool for modern Java versions and should be used instead of legacy commands whenever possible.

Information: On Windows, start the command prompt using "Run as Administrator" if you encounter permission-related errors when generating dumps.