Using Java Flight Recorder (JFR) in Quarkus

1. Introduction

Java Flight Recorder (JFR) is a powerful JVM tool for capturing events to monitor, profile, and troubleshoot applications. Integrating JFR with Quarkus gives us detailed insights into application behavior and performance by adding Quarkus-specific events.

In this article, we show how to set up JFR in a Quarkus project, generate custom events, and analyze the data to diagnose potential issues effectively.

2. Maven Dependency

To enable Java Flight Recorder in a Quarkus project, we need to add the quarkus-jfr extension. This extension integrates JFR with Quarkus, enabling custom Quarkus events for enhanced monitoring and diagnostics:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jfr</artifactId>
    <version>3.17.3</version>
</dependency>

3. Project Configuration

3.1. Creating a REST Endpoint

We’ll start by creating a simple REST endpoint. This resource will simulate a lightweight application interaction:

@Path("/hello")
public class JfrResource {
    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "hello";
    }
}

3.2. Starting Flight Recording

To ensure JFR starts recording automatically, we need to pass the appropriate JVM arguments. In our Quarkus application, we can do this in the application.properties file or as part of the command line when starting the application.

For development, let’s add the following JVM arguments:

quarkus dev -Djvm.args="-XX:StartFlightRecording=name=quarkus,dumponexit=true,filename=myrecording.jfr"

Besides starting JFR automatically when the application runs, dump the recording to myrecording.jfr when the application exits.

4. Saving JFR Events

By default, JFR dumps its recordings to the specified file (myrecording.jfr) when the application stops. We can trigger this by pressing CTRL+C in the terminal or using the jcmd command:

jcmd <PID> JFR.dump name=quarkus filename=myrecording.jfr

To find our application’s <PID>, we can use the jcmd command. This will list all running Java processes along with their process IDs.

5. Opening the JFR Dump File

Once we’ve recorded application events using JFR, analyzing the dump file is essential to uncover valuable insights. We can use two primary tools: the JFR CLI tool for quick command-line analysis and JDK Mission Control (JMC) for a detailed graphical view.

5.1. Using the JFR CLI

The JFR CLI is a lightweight tool for quick analysis directly from the terminal. To inspect the contents of a JFR file, we’ll use the jfr print command:

jfr print myrecording.jfr

After running the command, the output lists events, their timestamps, and associated details:

Event: io.quarkus.HttpRequest
  Method: GET
  Path: /hello
  ResponseCode: 200
  Duration: 3ms
Event: jdk.GarbageCollection
  StartTime: 2024-11-10T14:23:45.123Z
  Duration: 5ms
  Cause: System.gc()

To focus on specific event categories, we can use the –categories flag:

jfr print --categories "quarkus" myrecording.jfr

This command filters the output to show only events related to Quarkus, making it easier to analyze relevant data.

5.2. Using JDK Mission Control (JMC)

JMC provides a graphical interface with powerful visualization tools for an in-depth analysis. We can start JCM using the terminal or our system’s GUI to open JDK Mission Control. After launching JMC, the recorded file (myrecording.jfr) can be opened directly via the File > Open File menu. Once loaded, JMC organizes the captured data into intuitive views and categories:

The Event Browser in JMC allows us to explore specific events, including HTTP requests, memory usage, and garbage collection. Quarkus-specific events, such as io.quarkus.HttpRequest, are grouped under their respective categories. The timeline view helps correlate events over time, making identifying patterns and performance bottlenecks easier.

6. Adding Custom Events

In addition to the built-in events provided by Quarkus and the JVM, we can define custom events to monitor specific parts of our application. This is especially useful when tracking domain-specific behavior or performance metrics.

To define a custom event, extend the jdk.jfr.Event class and annotate it with @Name to specify its event name:

@Name("com.baeldung.DatabaseQueryEvent")
public class DatabaseQueryEvent extends Event {
    private final String query;
    private final long executionTime;
    public DatabaseQueryEvent(String query, long executionTime) {
        this.query = query;
        this.executionTime = executionTime;
    }
    public String getQuery() {
        return query;
    }
    public long getExecutionTime() {
        return executionTime;
    }
}

We can instantiate and commit the custom event within our application code. For instance, to record database query execution times:

DatabaseQueryEvent event = new DatabaseQueryEvent("SELECT * FROM users", 15);
event.commit();

Now, after running our program, we can view the custom-created events:

jfr print --events DatabaseQueryEvent myrecording.jfr

7. Conclusion

Java Flight Recorder, combined with Quarkus, is a powerful tool for monitoring and optimizing application performance. By using built-in and custom events, we can gain valuable insights into application behavior, diagnose issues, and improve efficiency.

As always, the code snippet is available over on GitHub.