Using JDK Flight Recorder
This guide explains how JDK Flight Recorder (JFR) can be extended to provide insight into your Quarkus application. insight into itself. JFR records various information from the Java standard API and JVM as events. By adding this extension, you can add custom Quarkus events to JFR. This will help you solve problems in your application.
JFR can be preconfigured to dump a file, and when the application exits, JFR will output the file. The file will contain the contents of the JFR event stream to which Quarkus custom events have also been added. You can, of course, get this file at any time you want, even if your application exits unexpectedly.
Pré-requisitos
Para concluir este guia, você precisa:
-
Cerca de 15 minutos
-
Um IDE
-
JDK 17+ installed with
JAVA_HOMEconfigured appropriately -
Apache Maven 3.9.7
-
Opcionalmente, o Quarkus CLI se você quiser usá-lo
-
Opcionalmente, Mandrel ou GraalVM instalado e configurado apropriadamente se você quiser criar um executável nativo (ou Docker se você usar uma compilação de contêiner nativo)
Criar o projeto Maven
Primeiro, precisamos de um novo projeto. Crie um novo projeto com o seguinte comando:
Para usuários do Windows:
-
Se estiver usando cmd, (não use barra invertida '\' e coloque tudo na mesma linha)
-
Se estiver usando o Powershell, envolva os parâmetros '-D' entre aspas duplas, por exemplo, '"-DprojectArtifactId=jfr-quickstart"'
This command generates the Maven project and imports the quarkus-jfr extension,
which includes the default JFR support.
If you already have your Quarkus project configured, you can add the quarkus-jfr extension
to your project by running the following command in your project base directory:
quarkus extension add quarkus-jfr./mvnw quarkus:add-extension -Dextensions='quarkus-jfr'./gradlew addExtension --extensions='quarkus-jfr'Isto irá adicionar o seguinte trecho no seu arquivo de build:
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-jfr</artifactId>
</dependency>implementation("io.quarkus:quarkus-jfr")Examine the Jakarta REST resource
Create a src/main/java/org/acme/jfr/JfrResource.java file with the following content:
package org.acme.jfr;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@Path("/hello")
public class JfrResource {
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return "hello";
}
}Notice that there is no JFR specific code included in the application. By default, requests sent to this endpoint will be recorded into JFR without any required code changes.
Running Quarkus applications and JFR
Now we are ready to run our application. We can launch the application with JFR configured to be enabled from the startup of the Java Virtual Machine.
quarkus dev -Djvm.args="-XX:StartFlightRecording=name=quarkus,dumponexit=true,filename=myrecording.jfr"./mvnw quarkus:dev -Djvm.args="-XX:StartFlightRecording=name=quarkus,dumponexit=true,filename=myrecording.jfr"./gradlew --console=plain quarkusDev -Djvm.args="-XX:StartFlightRecording=name=quarkus,dumponexit=true,filename=myrecording.jfr"With the JDK Flight Recorder and the application running, we can make a request to the provided endpoint:
$ curl http://localhost:8080/hello
helloThis is all that was needed to write the information to the JFR.
Save the JFR to a file
As mentioned above, the Quarkus application was configured to also start JFR at startup and dump it to a myrecording.jfr when it terminates.
So we can get the file when we hit CTRL+C or type q to stop the application.
Or, we can also dump with the jcmd command.
jcmd <PID> JFR.dump name=quarkus filename=myrecording.jfr
|
Running jcmd command give us a list of running Java processes and the PID of each process. |
Open JFR dump file
We can open a JFR dump using two tools: Jfr CLI and JDK Mission Control (JMC). It is also possible to read them using JFR APIs, but we won’t go into that here.
jfr CLI
The jfr CLI is a tool included in OpenJDK. The executable file is $JAVA_HOME/bin/jfr.
We can use the jfr CLI to see a list of events limited to those related to Quarkus in the dump file by doing the following.
jfr print --categories quarkus myrecording.jfr
JDK Mission Control
JMC is essentially a GUI viewer for JFR. Some distributions include JMC in OpenJDK binary, but if not, we need to download it manually. To see a list of events using the JMC, first we load the JFR file in the JMC as follows.
jmc -open myrecording.jfr
After opening the JFR file, we have two options. One is to view the events as a tabular list, and the other is to view the events on the threads in which they occurred, in chronological order.
To view Quarkus events in tabular style, select the Event Browser on the left side of the JMC, then open the Quarkus event type tree on the right side of the JMC.
To see Quarkus events in chronological order on a thread, select the Java application and Threads on the left side of the JMC.
The standard configuration does not show Quarkus events. We have to do three tasks to see the Quarkus events.
-
Right-click and select
Edit Thread Activity Lanes…. -
Select the plus button to add a new lane on the left side, then check to display that lane.
-
Select Quarkus as the event type that lane will display and press OK.
Now we can see the Quarkus events per thread.
|
Non-blocking is where multiple processes are processed apparently simultaneously in a single thread. Therefore, this extension records multiple JFR events concurrently, and a number of events might overlap on the JMC. This could make it difficult for you to see the events you want to see. To avoid this, we recommend to use Request ID to filter events so that you only see the information about the requests you want to see. |
Eventos
Identifying Requests
This extension works with the OpenTelemetry extension. The events recorded by this extension have a trace ID and a span ID. These are recorded with the OpenTelemetry IDs respectively.
This means that after we identify the trace and span IDs of interest from the UI provided by the OpenTelemetry implementation, we can immediately jump to the details in JFR using those IDs.
If we have not enabled the OpenTelemetry extension, this extension creates an ID for each request and links it to JFR events as a traceId. In this case, the span ID will be null.
For now, Quarkus only has REST events, but we plan to use this ID to link each event to each other as we add more events in the future.
Event Implementation Policy
When JFR starts recording an event, the event does not record to JFR yet, but when it commits that event, the event is recorded. Therefore, events that have started recording at dump time but have not yet been committed are not dumped. This is unavoidable due to the design of JFR. This means that events are not recorded forever if there are prolonged processing. Therefore, you will not be aware of prolonged processing.
To solve this problem, Quarkus can also record start and end events at the beginning and end of processing. These events are disabled by default. However, we can enable these events on JFR.(described below)
REST API Event
This event is recorded when either quarkus-rest or resteasy-classic extension is enabled.
The following three JFR events are recorded as soon as REST server processing is complete.
-
REST
-
REST Start
-
REST End
REST Event records the time period from the start of the REST process to the end of the REST server process.
REST Start Event records the start of the REST server process.
REST End Event records the end of the REST server process.
These events have the following information.
-
HTTP Method
-
URI
-
Resource Class
-
Resource Method
-
Client
HTTP Method records the HTTP Method accessed by the client. This will record a string of HTTP methods such as GET, POST, DELETE, and other general HTTP methods.
URI records the URI path accessed by the client. This does not include host names or port numbers.
Resource Class records the class that was executed. We can check whether the Resource Class was executed as expected by the HTTP Method and URI.
Resource Method records the method that was executed. We can check if the Resource Method was executed as expected by the HTTP Method and URI.
Client records information about the accessing client.
Native Image
Native image supports JDK Flight Recorder.
This extension also supports native images.
To enable JFR on Native image, it is usually built with --enable-monitoring.
However, we can enable JFR in Quarkus Native images by adding jfr to the configuration quarkus.native.monitoring.
There are two ways to set up this configuration: by including it in application.properties or by specifying it at build time.
The first method is to first configure settings in application.properties.
application.properties
quarkus.native.monitoring=jfrNext, simply build as ./mvnw package -Dnative.
The second way is to give -Dquarkus.native.monitoring=jfr at build time and build as ./mvnw package -Dnative -Dquarkus.native.monitoring=jfr.
Once we have finished building the Native image, we can run the native application with JFR as follows
target/your-application-runner -XX:StartFlightRecording=name=quarkus,dumponexit=true,filename=myrecording.jfr|
Note that at this time, GraalVM is not possible to record JFR on Windows native images. |
JFR configuration
We can use the JFR CLI to configure the events that JFR will record.
The configuration file, JFC file, is in XML format, so we can modify with a text editor.
However, we should use jfr configure, which is included in OpenJDK by default.
Here we create a configuration file in which RestStart and RestEnd events are recorded, which are not recorded by default.
jfr configure --input default.jfc +quarkus.RestStart#enabled=true +quarkus.RestEnd#enabled=true --output custom-rest.jfc
This creates custom-rest.jfc as a configuration file with RestStart and RestEnd enabled.
Now we are ready to run our application with new settings. We launch the application with JFR configured to be enabled from the startup of the Java Virtual Machine.
quarkus dev -Djvm.args="-XX:StartFlightRecording=name=quarkus,settings=./custom-rest.jfc,dumponexit=true,filename=myrecording.jfr"./mvnw quarkus:dev -Djvm.args="-XX:StartFlightRecording=name=quarkus,settings=./custom-rest.jfc,dumponexit=true,filename=myrecording.jfr"./gradlew --console=plain quarkusDev -Djvm.args="-XX:StartFlightRecording=name=quarkus,settings=./custom-rest.jfc,dumponexit=true,filename=myrecording.jfr"Developing new events into quarkus-jfr extension.
This section is for those who would like to add new events with this extension.
We recommend that new events be associated with existing events. Associations are useful when looking at the details of a process that is taking a long time. For example, a general REST application retrieves the data needed for processing from a data store. If REST events are not associated with datastore events, it is impossible to know which datastore events were processed in each REST request. When the two events are associated, we know immediately which datastore event was processed in each REST request.
|
Data store events are not implemented yet. |
The quarkus-jfr extension provides a Request ID for event association. See Identifying Requests for more information on Request IDs.
In specific code, the following two steps are required.
First, implement traceId and spanId on the new event as follows
The @TraceIdRelational and @SpanIdRelational attached to these events will provide the association.
import io.quarkus.jfr.runtime.SpanIdRelational;
import io.quarkus.jfr.runtime.TraceIdRelational;
import jdk.jfr.Description;
import jdk.jfr.Event;
import jdk.jfr.Label;
public class NewEvent extends Event {
@Label("Trace ID")
@Description("Trace ID to identify the request")
@TraceIdRelational
protected String traceId;
@Label("Span ID")
@Description("Span ID to identify the request if necessary")
@SpanIdRelational
protected String spanId;
// other properties which you want to add
// setters and getters
}Then you get the information to store in them from the IdProducer object’s getTraceId() and getSpanId().
import io.quarkus.jfr.runtime.IdProducer;
public class NewInterceptor {
@Inject
IdProducer idProducer;
private void recordedInvoke() {
NewEvent event = new NewEvent();
event.begin();
// The process you want to measure
event.end();
if (endEvent.shouldCommit()) {
event.setTraceId(idProducer.getTraceId());
event.setSpanId(idProducer.getSpanId());
// call other setters which you want to add
endEvent.commit();
}
}
}quarkus-jfr Configuration Reference
Propriedade de Configuração Fixa no Momento da Compilação - Todas as outras propriedades de configuração podem ser sobrepostas em tempo de execução.
Tipo |
Padrão |
|
|---|---|---|
If false, only quarkus-jfr events are not recorded even if JFR is enabled. In this case, Java standard API and virtual machine information will be recorded according to the setting. Default value is Environment variable: Show more |
boolean |
|
If false, only REST events in quarkus-jfr are not recorded even if JFR is enabled. In this case, other quarkus-jfr, Java standard API and virtual machine information will be recorded according to the setting. Default value is Environment variable: Show more |
boolean |
|
