Merge pull request quarkusio#44686 from cescoffier/virtual-thread-met…

…rics

Enable Virtual Thread Binder if micrometer-java21 is on the Classpath

.github/virtual-threads-tests.json

@@ -2,8 +2,8 @@
     "include": [
         {
             "category": "Main",
-            "timeout": 50,
-            "test-modules": "virtual-threads-disabled, grpc-virtual-threads, mailer-virtual-threads, redis-virtual-threads, rest-client-reactive-virtual-threads, resteasy-reactive-virtual-threads, vertx-event-bus-virtual-threads, scheduler-virtual-threads, quartz-virtual-threads",
+            "timeout": 60,
+            "test-modules": "virtual-threads-disabled, grpc-virtual-threads, mailer-virtual-threads, redis-virtual-threads, rest-client-reactive-virtual-threads, resteasy-reactive-virtual-threads, vertx-event-bus-virtual-threads, scheduler-virtual-threads, quartz-virtual-threads, metrics-virtual-threads",
             "os-name": "ubuntu-latest"
         },
         {

core/runtime/src/main/java/io/quarkus/runtime/util/JavaVersionUtil.java

@@ -13,6 +13,7 @@ public class JavaVersionUtil {
     private static boolean IS_JAVA_16_OR_OLDER;
     private static boolean IS_JAVA_17_OR_NEWER;
     private static boolean IS_JAVA_19_OR_NEWER;
+    private static boolean IS_JAVA_21_OR_NEWER;
 
     static {
         performChecks();
@@ -28,12 +29,14 @@ static void performChecks() {
             IS_JAVA_16_OR_OLDER = (first <= 16);
             IS_JAVA_17_OR_NEWER = (first >= 17);
             IS_JAVA_19_OR_NEWER = (first >= 19);
+            IS_JAVA_21_OR_NEWER = (first >= 21);
         } else {
             IS_JAVA_11_OR_NEWER = false;
             IS_JAVA_13_OR_NEWER = false;
             IS_JAVA_16_OR_OLDER = false;
             IS_JAVA_17_OR_NEWER = false;
             IS_JAVA_19_OR_NEWER = false;
+            IS_JAVA_21_OR_NEWER = false;
         }
 
         String vmVendor = System.getProperty("java.vm.vendor");
@@ -60,6 +63,10 @@ public static boolean isJava19OrHigher() {
         return IS_JAVA_19_OR_NEWER;
     }
 
+    public static boolean isJava21OrHigher() {
+        return IS_JAVA_21_OR_NEWER;
+    }
+
     public static boolean isGraalvmJdk() {
         return IS_GRAALVM_JDK;
     }

docs/src/main/asciidoc/virtual-threads.adoc

@@ -550,6 +550,38 @@ public class LoomUnitExampleTest {
 }
 ----
 
+== Virtual thread metrics
+
+You can enable the Micrometer Virtual Thread _binder_ by adding the following artifact to your application:
+
+[source,xml]
+----
+<dependency>
+    <groupId>io.micrometer</groupId>
+    <artifactId>micrometer-java21</artifactId>
+</dependency>
+----
+
+This binder keeps track of the number of pinning events and the number of virtual threads failed to be started or un-parked.
+See the https://docs.micrometer.io/micrometer/reference/reference/jvm.html#_java_21_metrics[MicroMeter documentation] for more information.
+
+You can explicitly disable the binder by setting the following property in your `application.properties`:
+
+[source,properties]
+----
+# The binder is automatically enabled if the micrometer-java21 dependency is present
+quarkus.micrometer.binder.virtual-threads.enabled=false
+----
+
+In addition, if the application is running on a JVM that does not support virtual threads (prior to Java 21), the binder is automatically disabled.
+
+You can associate tags to the collected metrics by setting the following properties in your `application.properties`:
+
+[source,properties]
+----
+quarkus.micrometer.binder.virtual-threads.tags=tag_1=value_1, tag_2=value_2
+----
+
 == Additional references
 
 - https://dl.acm.org/doi/10.1145/3583678.3596895[Considerations for integrating virtual threads in a Java framework: a Quarkus example in a resource-constrained environment]

extensions/micrometer/deployment/pom.xml

@@ -202,5 +202,19 @@
                 </plugins>
             </build>
         </profile>
+
+        <profile>
+            <id>Java 21+</id>
+            <activation>
+                <jdk>[21,)</jdk>
+            </activation>
+            <dependencies>
+                <dependency>
+                    <groupId>io.micrometer</groupId>
+                    <artifactId>micrometer-java21</artifactId>
+                    <scope>test</scope>
+                </dependency>
+            </dependencies>
+        </profile>
     </profiles>
 </project>

extensions/micrometer/deployment/src/main/java/io/quarkus/micrometer/deployment/binder/VirtualThreadBinderProcessor.java

@@ -0,0 +1,42 @@
+package io.quarkus.micrometer.deployment.binder;
+
+import java.util.function.BooleanSupplier;
+
+import io.quarkus.arc.deployment.AdditionalBeanBuildItem;
+import io.quarkus.deployment.annotations.BuildProducer;
+import io.quarkus.deployment.annotations.BuildStep;
+import io.quarkus.deployment.builditem.NativeMonitoringBuildItem;
+import io.quarkus.deployment.pkg.NativeConfig;
+import io.quarkus.micrometer.runtime.MicrometerRecorder;
+import io.quarkus.micrometer.runtime.config.MicrometerConfig;
+
+/**
+ * Add support for virtual thread metric collections.
+ */
+public class VirtualThreadBinderProcessor {
+    static final String VIRTUAL_THREAD_COLLECTOR_CLASS_NAME = "io.quarkus.micrometer.runtime.binder.virtualthreads.VirtualThreadCollector";
+
+    static final String VIRTUAL_THREAD_BINDER_CLASS_NAME = "io.micrometer.java21.instrument.binder.jdk.VirtualThreadMetrics";
+    static final Class<?> VIRTUAL_THREAD_BINDER_CLASS = MicrometerRecorder.getClassForName(VIRTUAL_THREAD_BINDER_CLASS_NAME);
+
+    static class VirtualThreadSupportEnabled implements BooleanSupplier {
+        MicrometerConfig mConfig;
+
+        public boolean getAsBoolean() {
+            return VIRTUAL_THREAD_BINDER_CLASS != null // The binder is in another Micrometer artifact
+                    && mConfig.checkBinderEnabledWithDefault(mConfig.binder.virtualThreads);
+        }
+    }
+
+    @BuildStep(onlyIf = VirtualThreadSupportEnabled.class)
+    AdditionalBeanBuildItem createCDIEventConsumer() {
+        return AdditionalBeanBuildItem.builder()
+                .addBeanClass(VIRTUAL_THREAD_COLLECTOR_CLASS_NAME)
+                .setUnremovable().build();
+    }
+
+    @BuildStep(onlyIf = VirtualThreadSupportEnabled.class)
+    void addNativeMonitoring(BuildProducer<NativeMonitoringBuildItem> nativeMonitoring) {
+        nativeMonitoring.produce(new NativeMonitoringBuildItem(NativeConfig.MonitoringOption.JFR));
+    }
+}

extensions/micrometer/deployment/src/test/java/io/quarkus/micrometer/deployment/binder/VirtualThreadMetricsDisabledTest.java

@@ -0,0 +1,41 @@
+package io.quarkus.micrometer.deployment.binder;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import jakarta.enterprise.inject.spi.BeanManager;
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.micrometer.runtime.binder.virtualthreads.VirtualThreadCollector;
+import io.quarkus.test.QuarkusUnitTest;
+
+public class VirtualThreadMetricsDisabledTest {
+
+    @RegisterExtension
+    static final QuarkusUnitTest config = new QuarkusUnitTest()
+            .withConfigurationResource("test-logging.properties")
+            .overrideConfigKey("quarkus.micrometer.binder.virtual-threads.enabled", "true")
+
+            .overrideConfigKey("quarkus.micrometer.binder-enabled-default", "false")
+            .overrideConfigKey("quarkus.micrometer.registry-enabled-default", "false")
+            .overrideConfigKey("quarkus.redis.devservices.enabled", "false")
+            .withEmptyApplication();
+
+    @Inject
+    BeanManager beans;
+
+    @Test
+    void testNoInstancePresentIfDisabled() {
+        assertTrue(
+                beans.createInstance().select()
+                        .stream().filter(this::isVirtualThreadCollector).findAny().isEmpty(),
+                "No VirtualThreadCollector expected");
+    }
+
+    private boolean isVirtualThreadCollector(Object bean) {
+        return bean.getClass().toString().equals(VirtualThreadCollector.class.toString());
+    }
+
+}

extensions/micrometer/deployment/src/test/java/io/quarkus/micrometer/deployment/binder/VirtualThreadMetricsTest.java

@@ -0,0 +1,44 @@
+package io.quarkus.micrometer.deployment.binder;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import jakarta.enterprise.inject.Instance;
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledForJreRange;
+import org.junit.jupiter.api.condition.JRE;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.micrometer.runtime.binder.virtualthreads.VirtualThreadCollector;
+import io.quarkus.test.QuarkusUnitTest;
+
+@EnabledForJreRange(min = JRE.JAVA_21)
+public class VirtualThreadMetricsTest {
+
+    @RegisterExtension
+    static final QuarkusUnitTest config = new QuarkusUnitTest()
+            .withConfigurationResource("test-logging.properties")
+            .overrideConfigKey("quarkus.redis.devservices.enabled", "false")
+            .withEmptyApplication();
+
+    @Inject
+    Instance<VirtualThreadCollector> collector;
+
+    @Test
+    void testInstancePresent() {
+        assertTrue(collector.isResolvable(), "VirtualThreadCollector expected");
+    }
+
+    @Test
+    void testBinderCreated() {
+        assertThat(collector.get().getBinder()).isNotNull();
+    }
+
+    @Test
+    void testTags() {
+        assertThat(collector.get().getTags()).isEmpty();
+    }
+
+}

extensions/micrometer/deployment/src/test/java/io/quarkus/micrometer/deployment/binder/VirtualThreadMetricsWithTagsTest.java

@@ -0,0 +1,53 @@
+package io.quarkus.micrometer.deployment.binder;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import jakarta.enterprise.inject.Instance;
+import jakarta.inject.Inject;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledForJreRange;
+import org.junit.jupiter.api.condition.JRE;
+import org.junit.jupiter.api.extension.RegisterExtension;
+
+import io.quarkus.micrometer.runtime.binder.virtualthreads.VirtualThreadCollector;
+import io.quarkus.test.QuarkusUnitTest;
+
+@EnabledForJreRange(min = JRE.JAVA_21)
+public class VirtualThreadMetricsWithTagsTest {
+
+    @RegisterExtension
+    static final QuarkusUnitTest config = new QuarkusUnitTest()
+            .withConfigurationResource("test-logging.properties")
+            .overrideConfigKey("quarkus.micrometer.binder.virtual-threads.tags", "k1=v1, k2=v2")
+            .overrideConfigKey("quarkus.redis.devservices.enabled", "false")
+            .withEmptyApplication();
+
+    @Inject
+    Instance<VirtualThreadCollector> collector;
+
+    @Test
+    void testInstancePresent() {
+        assertTrue(collector.isResolvable(), "VirtualThreadCollector expected");
+    }
+
+    @Test
+    void testBinderCreated() {
+        assertThat(collector.get().getBinder()).isNotNull();
+    }
+
+    @Test
+    void testTags() {
+        assertThat(collector.get().getTags()).hasSize(2)
+                .anySatisfy(t -> {
+                    assertThat(t.getKey()).isEqualTo("k1");
+                    assertThat(t.getValue()).isEqualTo("v1");
+                })
+                .anySatisfy(t -> {
+                    assertThat(t.getKey()).isEqualTo("k2");
+                    assertThat(t.getValue()).isEqualTo("v2");
+                });
+    }
+
+}