◀Table of Contents

Create a Heap Dump from a Native Executable

You can create a heap dump of a running executable to monitor its execution. Just like any other Java heap dump, it can be opened with the VisualVM tool.

You can build a native executable so that it dumps its heap in three ways:

Dump the initial heap of a native executable using the -XX:+DumpHeapAndExit command-line option.
Build a native executable with the -H:+AllowVMInspection option. Then create heap dumps sending USR1 (other supported signals are QUIT/BREAK for stack dumps and USR2 to dump runtime compilation information).
Create a heap dumps programmatically through the org.graalvm.nativeimage.VMRuntime#dumpHeap API.

All three approaches are described below.

Note: Creating heap dumps is not available on the Microsoft Windows platform.

Dump the Initial Heap of a Native Executable

Use the -XX:+DumpHeapAndExit command-line option to dump the initial heap of a native executable. This can be useful to identify which objects the Native Image build process allocated to the executable’s heap. For a HelloWorld example, use the option as follows:

$GRAALVM_HOME/bin/native-image HelloWorld -H:+AllowVMInspection
./helloworld -XX:+DumpHeapAndExit
Heap dump created at '/path/to/helloworld.hprof'.

Handle USR1 Signals

The following example is a simple multi-threaded Java application that runs for 60 seconds. This provides you with enough time to send it a USR1 signal. The application will handle the signal and create a heap dump in the application’s working directory. The heap dump will contain the Collection of Persons referenced by the static variable CROWD.

Follow these steps to build a native executable that will produce a heap dump when it receives a USR1 signal.

Save the following code in a file named SVMHeapDump.java:

import java.nio.charset.Charset;
import java.text.DateFormat;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Date;
import java.util.Random;
import org.graalvm.nativeimage.ProcessProperties;

public class SVMHeapDump extends Thread {
    static Collection<Person> CROWD = new ArrayList<>();
    static DateFormat DATE_FORMATTER = DateFormat.getDateTimeInstance();
    static int i = 0;
    static int runs = 60;
    static int sleepTime = 1000;
    @Override
    public void run() {
        System.out.println(DATE_FORMATTER.format(new Date()) + ": Thread started, it will run for " + runs + " seconds");
        while (i < runs) {
            // Add a new person to the collection
            CROWD.add(new Person());
            System.out.println("Sleeping for " + (runs - i) + " seconds.");
            try {
                Thread.sleep(sleepTime);
            } catch (InterruptedException ie) {
                System.out.println("Sleep interrupted.");
            }
            i++;
        }
    }

    /**
    * @param args the command line arguments
    */
    public static void main(String[] args) throws InterruptedException {
        // Add objects to the heap
        for (int i = 0; i < 1000; i++) {
            CROWD.add(new Person());
        }
        long pid = ProcessProperties.getProcessID();
        StringBuffer sb1 = new StringBuffer(100);
        sb1.append(DATE_FORMATTER.format(new Date()));
        sb1.append(": Hello GraalVM native image developer! \n");
        sb1.append("The PID of this process is: " + pid + "\n");
        sb1.append("Send it a signal: ");
        sb1.append("'kill -SIGUSR1 " + pid + "' \n");
        sb1.append("to dump the heap into the working directory.\n");
        sb1.append("Starting thread!");
        System.out.println(sb1);
        SVMHeapDump t = new SVMHeapDump();
        t.start();
        while (t.isAlive()) {
            t.join(0);
        }
        sb1 = new StringBuffer(100);
        sb1.append(DATE_FORMATTER.format(new Date()));
        sb1.append(": Thread finished after: ");
        sb1.append(i);
        sb1.append(" iterations.");
        System.out.println(sb1);
    }
}

class Person {
        private static Random R = new Random();
        private String name;
        private int age;
            
        public Person() {
            byte[] array = new byte[7];
            R.nextBytes(array);
            name = new String(array, Charset.forName("UTF-8"));
            age = R.nextInt(100);
        }
    }

Build a native executable:

Compile SVMHeapDump.java as follows:
```
 $JAVA_HOME/bin/javac SVMHeapDump.java
```
Build a native executable using the -H:+AllowVMInspection command-line option. (This causes the resulting native executable to produce a heap dump when it receives a USR1 signal.)
```
 $JAVA_HOME/bin/native-image SVMHeapDump -H:+AllowVMInspection
```
(The native-image builder creates a native executable from the SVMHeapDump.class. When the command completes, the native executable svmheapdump is created in the current directory.)
Run the application, send it a signal, and check the heap dump

Run the application:
```
 ./svmheapdump
 17 May 2022, 16:38:13: Hello GraalVM native image developer! 
 The PID of this process is: 57509
 Send it a signal: 'kill -SIGUSR1 57509' 
 to dump the heap into the working directory.
 Starting thread!
 17 May 2022, 16:38:13: Thread started, it will run for 60 seconds
```
Make a note of the PID and open a second terminal. Use the PID to send a signal to the application. For example, if the PID is 57509:
```
 kill -SIGUSR1 57509
```
The heap dump will be created in the working directory while the application continues to run. The heap dump can be opened with the VisualVM tool, as illustrated below.

Create a Heap Dump from within a Native Executable

The following example shows how to create a heap dump from a running native executable using VMRuntime.dumpHeap() if some condition is met. The condition to create a heap dump is provided as an option on the command line.

Save the code below in a file named SVMHeapDumpAPI.java.

 import java.io.File;
 import java.io.FileOutputStream;
 import java.io.IOException;
 import java.nio.charset.Charset;
 import java.text.DateFormat;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Date;
 import java.util.Random;
 import org.graalvm.nativeimage.VMRuntime;

 public class SVMHeapDumpAPI {
     static Collection<Person> CROWD = new ArrayList<>();

     /**
     * @param args the command line arguments
     */
     public static void main(String[] args) {   	
         // Populate the crowd
         for (int i = 0; i < 1000; i++) {
             CROWD.add(new Person());
         }
         StringBuffer sb1 = new StringBuffer(100);
         sb1.append(DateFormat.getDateTimeInstance().format(new Date()));
         sb1.append(": Hello GraalVM native image developer. \nYour command line options are: ");
         if (args.length > 0) {
             sb1.append(args[0]);
             System.out.println(sb1);
             if (args[0].equalsIgnoreCase("--heapdump")) {
                 createHeapDump();
             }
         } else {
             sb1.append("None");
             System.out.println(sb1);
         }
     }

     /**
     * Create a heap dump and save it into temp file
     */
     private static void createHeapDump() {
         try {
             File file = File.createTempFile("SVMHeapDumpAPI-", ".hprof");
             VMRuntime.dumpHeap(file.getAbsolutePath(), false);
             System.out.println("  Heap dump created " + file.getAbsolutePath() + ", size: " + file.length());
         } catch (UnsupportedOperationException unsupported) {
             System.err.println("Heap dump creation failed: " + unsupported.getMessage());
         } catch (IOException ioe) {
             System.err.println("IO went wrong: " + ioe.getMessage());
         }
     }

 }

 class Person {
         private static Random R = new Random();
         private String name;
         private int age;
            
         public Person() {
             byte[] array = new byte[7];
             R.nextBytes(array);
             name = new String(array, Charset.forName("UTF-8"));
             age = R.nextInt(100);
         }
     }

As in the earlier example, the application creates a Collection of Persons referenced by the static variable CROWD. It then checks the command line to see if heap dump has to be created, and then in method createHeapDump() creates the heap dump.

Build a native executable

Compile SVMHeapDumpAPI.java and build a native executable:
```
 $JAVA_HOME/bin/javac SVMHeapDumpAPI.java
 $JAVA_HOME/bin/native-image SVMHeapDumpAPI
```
When the command completes, the svmheapdumpapi native executable is created in the current directory.
Run the application and check the heap dump

Now you can run your native executable and create a heap dump from it with output similar to the following:
```
 ./svmheapdumpapi --heapdump
 Sep 15, 2020, 4:06:36 PM: Hello GraalVM native image developer.
 Your command line options are: --heapdump
   Heap dump created /var/folders/hw/s9d78jts67gdc8cfyq5fjcdm0000gp/T/SVMHeapDump-6437252222863577987.hprof, size: 8051959
```
The resulting heap dump can be then opened with the VisualVM tool like any other Java heap dump, as illustrated below.

Create a Heap Dump from a Native Executable

Dump the Initial Heap of a Native Executable

Handle USR1 Signals

Create a Heap Dump from within a Native Executable

Related Documentation