Build and Run Native Executables with JFR

JDK Flight Recorder (JFR) is a tool for collecting diagnostic and profiling data about a running Java application, built into the JVM. GraalVM Native Image supports JFR events and users can use the jdk.jfr.Event API with a similar experience to using JFR in the Java HotSpot VM.

To record JFR events when running a native executable, enable JFR support and JFR recording as described in this guide.

Note: JFR event recording is not yet supported on GraalVM JDK for Windows.

Enable JFR Support and Record Events at Run Time

To build a native executable with the JFR events support, you first need to add the --enable-monitoring=jfr option when invoking the native-image tool. Then enable the system, start a recording, and configure logging at native executable run time:

Follow the steps below to practice building a native executable with JFR support and recording events at run time.

Note: Make sure you have installed a GraalVM JDK. The easiest way to get started is with SDKMAN!. For other installation options, visit the Downloads section.

  1. Install VisualVM by running:
     gu install visualvm
    
  2. Save the following code to the file named JFRDemo.java.

     import jdk.jfr.Event;
     import jdk.jfr.Description;
     import jdk.jfr.Label;
    
     public class JFRDemo {
    
       @Label("Hello World")
       @Description("Build and run a native executable with JFR.")
       static class HelloWorldEvent extends Event {
           @Label("Message")
           String message;
       }
    
       public static void main(String... args) {
           HelloWorldEvent event = new HelloWorldEvent();
           event.message = "Hello, World!";
           event.commit();
       }
     }
    

    This demo application consists of a simple class and JDK library classes. It creates an event, labelled with the @Label annotation from the jdk.jfr.* package. If you run this application, it will not print anything and just run that event.

  3. Compile the Java file using the GraalVM JDK:
     $JAVA_HOME/bin/javac JFRDemo.java
    

    It creates two class files: JFRDemo$HelloWorldEvent.class and JFRDemo.class.

  4. Build a native executable with the VM inspection enabled:
     $JAVA_HOME/bin/native-image --enable-monitoring=jfr JFRDemo
    

    The --enable-monitoring=jfr option enables features such as JFR that can be used to inspect the VM.

  5. Run the executable and start recording:
     ./jfrdemo -XX:StartFlightRecording="filename=recording.jfr"
    

    This command runs the application as a native executable. The -XX:StartFlightRecording option enables the built-in Flight Recorder and starts recording to a specified binary file, recording.jfr.

  6. Start VisualVM to view the contents of the recording file in a user-friendly way. GraalVM provides VisualVM in the core installation. To start the tool, run:

     $JAVA_HOME/bin/jvisualvm
    
  7. Go to File, then Add JFR Snapshot, browse recording.jfr, and open the selected file. Confirm the display name and click OK. Once opened, there is a bunch of options you can check: Monitoring, Threads, Exceptions, etc., but you should be mostly interested in the events browsing. It will look something like this:

    JDK Flight Recorder

    Alternatively, you can view the contents of the recording file in the console window by running this command:

     $JAVA_HOME/bin/jfr print recording.jfr
    

    It prints all the events recorded by Flight Recorder.