Refactor JFR extension structure: introduce SPI modules

Author: chiroito

bom/application/pom.xml

@@ -6500,11 +6500,21 @@
             </dependency>
 
             <!-- JDK Flight Recorder -->
+            <dependency>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-jfr-api</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.quarkus</groupId>
                 <artifactId>quarkus-jfr</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-jfr-deployment-spi</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>io.quarkus</groupId>
                 <artifactId>quarkus-jfr-deployment</artifactId>

core/deployment/src/main/java/io/quarkus/deployment/Capability.java

@@ -41,6 +41,7 @@ public interface Capability {
 
     String JAXB = QUARKUS_PREFIX + ".jaxb";
     String JAXP = QUARKUS_PREFIX + ".jaxp";
+    String JFR = QUARKUS_PREFIX + ".jfr";
 
     String KOTLIN = QUARKUS_PREFIX + ".kotlin";
 

docs/src/main/asciidoc/jfr.adoc

@@ -4,14 +4,14 @@ and pull requests should be submitted there:
 https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
 ////
 [id="jfr"]
-= Using Java Flight Recorder
+= Using JDK Flight Recorder
 include::_attributes.adoc[]
 :categories: observability
-:summary: This guide explains how Java Flight Recorder (JFR) can be extended to provide additional insight into your Quarkus application.
+:summary: This guide explains how JDK Flight Recorder (JFR) can be extended to provide additional insight into your Quarkus application.
 :topics: observability,jfr
 :extensions: io.quarkus:quarkus-jfr
 
-This guide explains how https://openjdk.org/jeps/328[Java Flight Recorder] (JFR) can be extended to provide additional insight into your Quarkus application.
+This guide explains how https://openjdk.org/jeps/328[Flight Recorder] can be extended to provide additional insight into your Quarkus application.
 JFR records various information from the Java standard API and JVM as events.
 By adding the Quarkus JFR extension, you can add custom Quarkus events to JFR. This will help you solve potential problems in your application.
 
@@ -99,7 +99,7 @@ We can launch the application with JFR configured to be enabled from the startup
 :dev-additional-parameters: -Djvm.args="-XX:StartFlightRecording=name=quarkus,dumponexit=true,filename=myrecording.jfr"
 include::{includes}/devtools/dev.adoc[]
 
-With the Java Flight Recorder and the application running, we can make a request to the provided endpoint:
+With the JDK Flight Recorder and the application running, we can make a request to the provided endpoint:
 
 [source,shell]
 ----
@@ -269,7 +269,7 @@ Extension::
 
 === Native Image
 
-Native executables supports Java Flight Recorder.
+Native executables supports JDK Flight Recorder.
 This extension also supports native executables.
 
 To enable JFR on native executables, it is usually built with `--enable-monitoring`.
@@ -329,7 +329,40 @@ include::{includes}/devtools/dev.adoc[]
 
 == Adding new events
 
-This section is for those who would like to add new events to this extension.
+This section is for extension authors who want to add new JFR events.
+
+=== Depending on the API module
+
+The Quarkus JFR extension separates the public API from the runtime implementation.
+As a result, other extensions can implement JFR-based instrumentation by depending only on the JFR API module, without adding a dependency on the Quarkus JFR extension implementation itself.
+
+At deployment time, an extension can detect whether the application has enabled the Quarkus JFR extension by using Quarkus capabilities:
+
+[source,java]
+----
+import io.quarkus.deployment.Capabilities;
+import io.quarkus.deployment.Capability;
+import io.quarkus.deployment.annotations.BuildStep;
+import io.quarkus.deployment.annotations.BuildSteps;
+
+@BuildSteps
+class MyProcessor {
+
+    @BuildStep
+    void step(Capabilities capabilities) {
+        if (capabilities.isPresent(Capability.JFR)) {
+            // The Quarkus JFR extension is enabled
+            // Register JFR-related build items, bytecode transformations, etc.
+        }
+    }
+}
+----
+
+This pattern allows your extension to:
+* compile against stable API types only, and
+* activate JFR instrumentation only when the Quarkus JFR extension is present in the application.
+
+=== Associating events by request
 
 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.
@@ -345,14 +378,17 @@ Datastore 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.
+In code, you typically need the following two steps.
+
+==== 1) Add trace/span identifiers to your event
+
+Implement `traceId` and `spanId` on the new event as follows.
+The `@TraceIdRelational` and `@SpanIdRelational` annotations mark these fields as relational identifiers used for association.
 
 [source,java]
 ----
-import io.quarkus.jfr.runtime.SpanIdRelational;
-import io.quarkus.jfr.runtime.TraceIdRelational;
+import io.quarkus.jfr.api.SpanIdRelational;
+import io.quarkus.jfr.api.TraceIdRelational;
 import jdk.jfr.Description;
 import jdk.jfr.Event;
 import jdk.jfr.Label;
@@ -374,11 +410,13 @@ public class NewEvent extends Event {
 }
 ----
 
-Then you get the information to store in the event from the `IdProducer` object's `getTraceId()` and `getSpanId()`.
+==== 2) Populate the identifiers from the IdProducer
+
+Obtain the values to store in the event from an `IdProducer` and set them just before committing the event.
 
 [source,java]
 ----
-import io.quarkus.jfr.runtime.IdProducer;
+import io.quarkus.jfr.api.IdProducer;
 
 public class NewInterceptor {
 
@@ -392,11 +430,11 @@ public class NewInterceptor {
         // The process you want to measure
 
         event.end();
-        if (endEvent.shouldCommit()) {
+        if (event.shouldCommit()) {
             event.setTraceId(idProducer.getTraceId());
             event.setSpanId(idProducer.getSpanId());
             // call other setters which you want to add
-            endEvent.commit();
+            event.commit();
         }
     }
 }

extensions/jfr/deployment-spi/pom.xml

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <artifactId>quarkus-jfr-parent</artifactId>
+        <groupId>io.quarkus</groupId>
+        <version>999-SNAPSHOT</version>
+    </parent>
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>quarkus-jfr-deployment-spi</artifactId>
+    <name>Quarkus - JFR - SPI</name>
+    <description>Artifact that provides BuildItems specific to JFR extension</description>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-core-deployment</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-jfr-api</artifactId>
+        </dependency>
+    </dependencies>
+</project>

extensions/jfr/deployment/pom.xml

@@ -16,6 +16,10 @@
             <artifactId>quarkus-jfr</artifactId>
             <version>${project.version}</version>
         </dependency>
+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-jfr-deployment-spi</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.quarkus</groupId>
             <artifactId>quarkus-arc-deployment</artifactId>

extensions/jfr/deployment/src/main/java/io/quarkus/jfr/deployment/JfrProcessor.java

@@ -15,18 +15,19 @@
 import io.quarkus.deployment.annotations.BuildSteps;
 import io.quarkus.deployment.annotations.ExecutionTime;
 import io.quarkus.deployment.annotations.Record;
+import io.quarkus.deployment.builditem.CapabilityBuildItem;
 import io.quarkus.deployment.builditem.FeatureBuildItem;
 import io.quarkus.deployment.builditem.nativeimage.RuntimeInitializedClassBuildItem;
-import io.quarkus.jfr.runtime.JfrRecorder;
-import io.quarkus.jfr.runtime.OTelIdProducer;
-import io.quarkus.jfr.runtime.QuarkusIdProducer;
-import io.quarkus.jfr.runtime.http.rest.classic.ClassicServerFilter;
-import io.quarkus.jfr.runtime.http.rest.classic.ClassicServerRecorderProducer;
-import io.quarkus.jfr.runtime.http.rest.reactive.ReactiveServerFilters;
-import io.quarkus.jfr.runtime.http.rest.reactive.ReactiveServerRecorderProducer;
-import io.quarkus.jfr.runtime.http.rest.reactive.ServerStartRecordingHandler;
-import io.quarkus.jfr.runtime.runtime.JfrRuntimeBean;
-import io.quarkus.jfr.runtime.runtime.QuarkusRuntimeInfo;
+import io.quarkus.jfr.runtime.internal.JfrRecorder;
+import io.quarkus.jfr.runtime.internal.OTelIdProducer;
+import io.quarkus.jfr.runtime.internal.QuarkusIdProducer;
+import io.quarkus.jfr.runtime.internal.http.rest.classic.ClassicServerEventRecorderProducer;
+import io.quarkus.jfr.runtime.internal.http.rest.classic.ClassicServerFilter;
+import io.quarkus.jfr.runtime.internal.http.rest.reactive.ReactiveServerEventRecorderProducer;
+import io.quarkus.jfr.runtime.internal.http.rest.reactive.ReactiveServerFilters;
+import io.quarkus.jfr.runtime.internal.http.rest.reactive.ServerStartRecordingHandler;
+import io.quarkus.jfr.runtime.internal.runtime.JfrRuntimeBean;
+import io.quarkus.jfr.runtime.internal.runtime.QuarkusRuntimeInfo;
 import io.quarkus.resteasy.common.spi.ResteasyJaxrsProviderBuildItem;
 import io.quarkus.resteasy.reactive.server.spi.GlobalHandlerCustomizerBuildItem;
 import io.quarkus.resteasy.reactive.spi.CustomContainerRequestFilterBuildItem;
@@ -39,6 +40,11 @@ FeatureBuildItem feature() {
         return new FeatureBuildItem(Feature.JFR);
     }
 
+    @BuildStep
+    CapabilityBuildItem capability() {
+        return new CapabilityBuildItem(Capability.JFR);
+    }
+
     @BuildStep
     @Record(ExecutionTime.RUNTIME_INIT)
     void registerVersion(List<FeatureBuildItem> features, BuildProducer<AdditionalBeanBuildItem> additionalBeans,
@@ -88,7 +94,7 @@ void registerRestIntegration(Capabilities capabilities,
         if (capabilities.isPresent(Capability.RESTEASY_REACTIVE)) {
 
             additionalBeans.produce(AdditionalBeanBuildItem.builder().setUnremovable()
-                    .addBeanClasses(ReactiveServerRecorderProducer.class)
+                    .addBeanClasses(ReactiveServerEventRecorderProducer.class)
                     .build());
 
             filterBeans
@@ -106,7 +112,7 @@ void registerResteasyClassicIntegration(Capabilities capabilities,
         if (capabilities.isPresent(Capability.RESTEASY)) {
 
             additionalBeans.produce(AdditionalBeanBuildItem.builder().setUnremovable()
-                    .addBeanClasses(ClassicServerRecorderProducer.class)
+                    .addBeanClasses(ClassicServerEventRecorderProducer.class)
                     .build());
 
             resteasyJaxrsProviderBuildItemBuildProducer

…arkus/jfr/test/JfrConfigurationTest.java …jfr/deployment/JfrConfigurationTest.javaextensions/jfr/deployment/src/test/java/io/quarkus/jfr/test/JfrConfigurationTest.java renamed to extensions/jfr/deployment/src/test/java/io/quarkus/jfr/deployment/JfrConfigurationTest.java extensions/jfr/deployment/src/test/java/io/quarkus/jfr/test/JfrConfigurationTest.java renamed to extensions/jfr/deployment/src/test/java/io/quarkus/jfr/deployment/JfrConfigurationTest.java

@@ -1,4 +1,4 @@
-package io.quarkus.jfr.test;
+package io.quarkus.jfr.deployment;
 
 import static org.junit.jupiter.api.Assertions.assertFalse;
 
@@ -7,7 +7,7 @@
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.RegisterExtension;
 
-import io.quarkus.jfr.runtime.config.JfrRuntimeConfig;
+import io.quarkus.jfr.runtime.internal.config.JfrRuntimeConfig;
 import io.quarkus.test.QuarkusUnitTest;
 
 public class JfrConfigurationTest {

extensions/jfr/deployment/src/test/java/io/quarkus/jfr/deployment/JfrIdTest.java

@@ -0,0 +1,30 @@
+package io.quarkus.jfr.deployment;
+
+import jakarta.enterprise.context.control.ActivateRequestContext;
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.jfr.api.IdProducer;
+import io.quarkus.test.QuarkusUnitTest;
+
+@ActivateRequestContext
+public class JfrIdTest {
+
+    @RegisterExtension
+    static final QuarkusUnitTest TEST = new QuarkusUnitTest();
+
+    @Inject
+    IdProducer idProducer;
+
+    @Test
+    public void test() {
+        String traceId = idProducer.getTraceId();
+        String spanId = idProducer.getSpanId();
+
+        Assertions.assertNotNull(traceId);
+        Assertions.assertNull(spanId);
+    }
+}

…jfr/test/runtime/JfrRuntimeBeanTest.java …ployment/runtime/JfrRuntimeBeanTest.javaextensions/jfr/deployment/src/test/java/io/quarkus/jfr/test/runtime/JfrRuntimeBeanTest.java renamed to extensions/jfr/deployment/src/test/java/io/quarkus/jfr/deployment/runtime/JfrRuntimeBeanTest.java extensions/jfr/deployment/src/test/java/io/quarkus/jfr/test/runtime/JfrRuntimeBeanTest.java renamed to extensions/jfr/deployment/src/test/java/io/quarkus/jfr/deployment/runtime/JfrRuntimeBeanTest.java

@@ -1,4 +1,4 @@
-package io.quarkus.jfr.test.runtime;
+package io.quarkus.jfr.deployment.runtime;
 
 import jakarta.inject.Inject;
 
@@ -9,7 +9,7 @@
 import org.junit.jupiter.api.extension.RegisterExtension;
 
 import io.quarkus.builder.Version;
-import io.quarkus.jfr.runtime.runtime.QuarkusRuntimeInfo;
+import io.quarkus.jfr.runtime.internal.runtime.QuarkusRuntimeInfo;
 import io.quarkus.runtime.ImageMode;
 import io.quarkus.test.QuarkusUnitTest;
 

…/test/runtime/JfrRuntimeDisableTest.java …yment/runtime/JfrRuntimeDisableTest.javaextensions/jfr/deployment/src/test/java/io/quarkus/jfr/test/runtime/JfrRuntimeDisableTest.java renamed to extensions/jfr/deployment/src/test/java/io/quarkus/jfr/deployment/runtime/JfrRuntimeDisableTest.java extensions/jfr/deployment/src/test/java/io/quarkus/jfr/test/runtime/JfrRuntimeDisableTest.java renamed to extensions/jfr/deployment/src/test/java/io/quarkus/jfr/deployment/runtime/JfrRuntimeDisableTest.java

@@ -1,4 +1,4 @@
-package io.quarkus.jfr.test.runtime;
+package io.quarkus.jfr.deployment.runtime;
 
 import java.io.IOException;
 import java.nio.file.Files;