Add ability for users to configure settings related to virtual threads meters

docs/src/main/asciidoc/includes/guides/metrics.adoc

@@ -405,22 +405,66 @@ endif::se-flavor[]
 [[observing-vthreads]]
 ==== Observing Virtual Threads Behavior
 :vthreads-prefix: vthreads
-Helidon maintains several {metrics} related to virtual threads as summarized in the next table.
+Helidon maintains several {metrics} related to virtual threads as summarized in the next table. Helidon might rely on Java Flight Recorder (JFR) events and JMX MXBeans in computing the {metric} values. Be aware that limitations or changes in the values provided by these sources are outside the control of Helidon.
 
 .{metrics_uc} for Virtual Threads
-[cols="2,5,1"]
+[cols="2,5,3,1"]
 |===
-| {metric_uc} name | Usage | Reported by default
+| {metric_uc} name | Usage | Source | Reported by default
 
-| `{vthreads-prefix}.count` | Current number of active virtual threads. | no
-| `{vthreads-prefix}.pinned` | Number of times virtual threads have been pinned. | yes
-| `{vthreads-prefix}.recentPinned` | Distribution of the duration of thread pinning. ^1^ | yes
-| `{vthreads-prefix}.started` | Number of virtual threads started. | no
-| `{vthreads-prefix}.submitFailed` | Number of times submissions of a virtual thread to a platform carrier thread failed. | yes
+| `{vthreads-prefix}.count` | Current number of active virtual threads. | JFR `jdk.virtualThreadStart` and `jdk.virtualThreadEnd` events| no
+| `{vthreads-prefix}.pinned` | Number of times virtual threads have been pinned. | JFR `jdk.virtualThreadPinned` event | yes
+| `{vthreads-prefix}.recentPinned` | Distribution of the duration of thread pinning. ^1^ | JFR `jdk.virtualThreadPinned` event | yes
+| `{vthreads-prefix}.started` | Number of virtual threads started. | JFR `jdk.virtualThreadStart` event | no
+| `{vthreads-prefix}.submitFailed` | Number of times submissions of a virtual thread to a platform carrier thread failed. | JFR `jdk.virtualThreadSubmitFailed` event | yes
 |===
 ^1^ Distribution summaries can discard stale data, so the `recentPinned` summary might not reflect all thread pinning activity.
 
 // tag::virtualThreadsMetricsConfig[]
+==== Configuring Virtual Threads {metrics_uc}
+===== Disabling Virtual Threads {metrics_uc} Entirely
+Gathering data to compute the {metrics} for virtual threads is designed to be as efficient as possible, but doing so still imposes a small load on the server and by default Helidon exposes only the {metrics} related to virtual threads noted in the table above.
+
+To disable all {metrics} describing virtual threads, include a config setting as shown in the following example:
+
+.Disabling virtual thread metrics entirely
+ifdef::mp-flavor[]
+[source,properties]
+----
+metrics.virtual-threads.enabled = false
+----
+endif::mp-flavor[]
+ifdef::se-flavor[]
+[source,yaml]
+----
+metrics:
+  virtual-threads:
+    enabled: false
+----
+endif::se-flavor[]
+
+===== Controlling Measurements of Pinned Virtual Threads
+Helidon measures pinned virtual threads only when the thread is pinned for a length of time at or above a threshold. Control the threshold by configuring the threshold as shown in the example below.
+
+.Setting virtual thread pinning threshold to 100 ms
+ifdef::mp-flavor[]
+[source,properties]
+----
+metrics.virtual-threads.pinned.threshold=PT0.100S
+----
+endif::mp-flavor[]
+ifdef::se-flavor[]
+[source,yaml]
+----
+metrics:
+  virtual-threads:
+    pinned:
+      threshold: PT0.100S
+----
+endif::se-flavor[]
+The threshold value is a `Duration` string, such as `PT0.100S` for 100 milliseconds.
+
+===== Controlling Virtual Thread Counts
 For performance reasons Helidon does not by default report the {metrics} related to the count of virtual threads.
 Enable these {metrics} using configuration.
 

metrics/api/src/main/java/io/helidon/metrics/api/MetricsConfigBlueprint.java

@@ -15,6 +15,7 @@
  */
 package io.helidon.metrics.api;
 
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
@@ -198,6 +199,15 @@ static List<Tag> createTags(String pairs) {
     @Option.DefaultBoolean(false)
     boolean restRequestEnabled();
 
+    /**
+     * Whether Helidon should expose meters related to virtual threads.
+     *
+     * @return true to include meters related to virtual threads
+     */
+    @Option.Configured("virtual-threads.enabled")
+    @Option.DefaultBoolean(true)
+    boolean virtualThreadsEnabled();
+
     /**
      * Whether the virtual thread count should be exposed as a meter.
      * <p>
@@ -210,6 +220,15 @@ static List<Tag> createTags(String pairs) {
     @Option.DefaultBoolean(false)
     boolean virtualThreadCountEnabled();
 
+    /**
+     * Threshold for sampling pinned virtual threads to include in the pinned threads meter.
+     *
+     * @return threshold used to filter virtual thread pinning events
+     */
+    @Option.Configured("virtual-threads.pinned.threshold")
+    @Option.Default("PT0.020S")
+    Duration virtualThreadsPinnedThreshold();
+
     /**
      * Metrics configuration node.
      *

metrics/system-meters/src/main/java/io/helidon/metrics/systemmeters/VThreadSystemMetersProvider.java

@@ -25,6 +25,7 @@
 import io.helidon.metrics.api.Gauge;
 import io.helidon.metrics.api.Meter;
 import io.helidon.metrics.api.Metrics;
+import io.helidon.metrics.api.MetricsConfig;
 import io.helidon.metrics.api.MetricsFactory;
 import io.helidon.metrics.api.Timer;
 import io.helidon.metrics.spi.MetersProvider;
@@ -63,6 +64,7 @@ public class VThreadSystemMetersProvider implements MetersProvider {
     private long pinnedVirtualThreads;
     private long virtualThreads;
     private long virtualThreadStarts;
+    private long pinnedVirtualThreadsThresholdMillis;
 
     /**
      * For service loading.
@@ -73,7 +75,15 @@ public VThreadSystemMetersProvider() {
     @Override
     public Collection<Meter.Builder<?, ?>> meterBuilders(MetricsFactory metricsFactory) {
 
-        var rs = new RecordingStream();
+        MetricsConfig metricsConfig = metricsFactory.metricsConfig();
+        if (!metricsConfig.virtualThreadsEnabled()) {
+            return List.of();
+        }
+
+        var recordingStream = new RecordingStream();
+        pinnedVirtualThreadsThresholdMillis = metricsConfig.virtualThreadsPinnedThreshold().toMillis();
+        recordingStream.setSettings(Map.of("jdk.VirtualThreadPinned#threshold",
+                                            pinnedVirtualThreadsThresholdMillis + " ms"));
 
         List<Meter.Builder<?, ?>> meterBuilders = new ArrayList<>(List.of(
                 Gauge.builder(METER_NAME_PREFIX + SUBMIT_FAILURES, () -> virtualThreadSubmitFails)
@@ -86,7 +96,7 @@ public VThreadSystemMetersProvider() {
                         .description("Pinned virtual thread durations")
                         .scope(METER_SCOPE)));
 
-        listenFor(rs, Map.of("jdk.VirtualThreadSubmitFailed", this::recordSubmitFail,
+        listenFor(recordingStream, Map.of("jdk.VirtualThreadSubmitFailed", this::recordSubmitFail,
                              "jdk.VirtualThreadPinned", this::recordThreadPin));
 
         if (metricsFactory.metricsConfig().virtualThreadCountEnabled()) {
@@ -97,17 +107,21 @@ public VThreadSystemMetersProvider() {
                                       .description("Number of virtual thread starts")
                                       .scope(METER_SCOPE));
 
-            listenFor(rs, Map.of("jdk.VirtualThreadStart", this::recordThreadStart,
+            listenFor(recordingStream, Map.of("jdk.VirtualThreadStart", this::recordThreadStart,
                                  "jdk.VirtualThreadEnd", this::recordThreadEnd));
         }
 
-        rs.startAsync();
+        recordingStream.startAsync();
         return meterBuilders;
     }
 
+    // For testing
+    long pinnedVirtualThreadsThresholdMillis() {
+        return pinnedVirtualThreadsThresholdMillis;
+    }
+
     private static void listenFor(RecordingStream rs, Map<String, Consumer<RecordedEvent>> events) {
-        // Enable events of interest explicitly (as well as registering the callback) to be sure we get the events
-        // despite what the defaults might be.
+        // Enable events of interest explicitly (as well as registering the callback) to be sure we receive the events we need.
 
         events.forEach((eventName, callback) -> {
             rs.enable(eventName);

metrics/system-meters/src/test/java/io/helidon/metrics/systemmeters/TestVirtualThreadsMetersConfigs.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.helidon.metrics.systemmeters;
+
+import java.util.Map;
+
+import io.helidon.config.Config;
+import io.helidon.config.ConfigSources;
+import io.helidon.metrics.api.Gauge;
+import io.helidon.metrics.api.MetricsFactory;
+import io.helidon.metrics.api.Timer;
+
+import org.junit.jupiter.api.Test;
+
+import static io.helidon.metrics.systemmeters.MeterBuilderMatcher.withName;
+import static io.helidon.metrics.systemmeters.VThreadSystemMetersProvider.COUNT;
+import static io.helidon.metrics.systemmeters.VThreadSystemMetersProvider.METER_NAME_PREFIX;
+import static io.helidon.metrics.systemmeters.VThreadSystemMetersProvider.PINNED;
+import static io.helidon.metrics.systemmeters.VThreadSystemMetersProvider.RECENT_PINNED;
+import static io.helidon.metrics.systemmeters.VThreadSystemMetersProvider.STARTS;
+import static io.helidon.metrics.systemmeters.VThreadSystemMetersProvider.SUBMIT_FAILURES;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.allOf;
+import static org.hamcrest.Matchers.containsInAnyOrder;
+import static org.hamcrest.Matchers.empty;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.instanceOf;
+
+class TestVirtualThreadsMetersConfigs {
+
+    @Test
+    void checkDefault() {
+        Config config = Config.just(ConfigSources.create(Map.of()));
+        MetricsFactory metricsFactory = MetricsFactory.getInstance(config);
+        VThreadSystemMetersProvider provider = new VThreadSystemMetersProvider();
+        var meterBuilders = provider.meterBuilders(metricsFactory);
+        assertThat("Default meter builders",
+                   meterBuilders,
+                   containsInAnyOrder(allOf(withName(equalTo(METER_NAME_PREFIX + PINNED)),
+                                            instanceOf(Gauge.Builder.class)),
+                                      allOf(withName(equalTo(METER_NAME_PREFIX + SUBMIT_FAILURES)),
+                                            instanceOf(Gauge.Builder.class)),
+                                      allOf(withName(equalTo(METER_NAME_PREFIX + RECENT_PINNED)),
+                                            instanceOf(Timer.Builder.class))));
+        assertThat("Pinned thread threshold", provider.pinnedVirtualThreadsThresholdMillis(), equalTo(20L));
+    }
+
+    @Test
+    void checkVirtualThreadMetersDisabled() {
+        Config config = Config.just(ConfigSources.create(Map.of("virtual-threads.enabled", "false")));
+        MetricsFactory metricsFactory = MetricsFactory.getInstance(config);
+        VThreadSystemMetersProvider provider = new VThreadSystemMetersProvider();
+        var meterBuilders = provider.meterBuilders(metricsFactory);
+        assertThat("Meter builders with virtual threads meters disabled", meterBuilders, empty());
+    }
+
+    @Test
+    void checkVirtualThreadCountMetersEnabled() {
+        Config config = Config.just(ConfigSources.create(Map.of("virtual-threads.count.enabled", "true")));
+        MetricsFactory metricsFactory = MetricsFactory.getInstance(config);
+        VThreadSystemMetersProvider provider = new VThreadSystemMetersProvider();
+        var meterBuilders = provider.meterBuilders(metricsFactory);
+
+        assertThat("Default meter builders",
+                   meterBuilders,
+                   containsInAnyOrder(allOf(withName(equalTo(METER_NAME_PREFIX + PINNED)),
+                                            instanceOf(Gauge.Builder.class)),
+                                      allOf(withName(equalTo(METER_NAME_PREFIX + SUBMIT_FAILURES)),
+                                            instanceOf(Gauge.Builder.class)),
+                                      allOf(withName(equalTo(METER_NAME_PREFIX + RECENT_PINNED)),
+                                            instanceOf(Timer.Builder.class)),
+                                      allOf(withName(equalTo(METER_NAME_PREFIX + COUNT)),
+                                            instanceOf(Gauge.Builder.class)),
+                                      allOf(withName(equalTo(METER_NAME_PREFIX + STARTS)),
+                                            instanceOf(Gauge.Builder.class))));
+
+    }
+
+    @Test
+    void checkPinnedThreadThreshold() {
+        Config config = Config.just(ConfigSources.create(Map.of("virtual-threads.pinned.threshold", "PT0.040S")));
+        MetricsFactory metricsFactory = MetricsFactory.getInstance(config);
+        VThreadSystemMetersProvider provider = new VThreadSystemMetersProvider();
+        provider.meterBuilders(metricsFactory);
+
+        assertThat("Pinned thread threshold", provider.pinnedVirtualThreadsThresholdMillis(), equalTo(40L));
+
+    }
+
+}