Add virtual thread support for gRPC and HTTP servers on JDK 25+ (#13705)

  Add virtual thread support for gRPC and Armeria HTTP servers on JDK 25+

  Enable virtual-thread-per-task executors for all 4 gRPC and 7 HTTP
  server handler pools when running on JDK 25+, with automatic fallback
  to platform thread pools on older JDKs. JDK 25 is required as the
  first LTS with the synchronized pinning fix (JEP 491).

  Key changes:
  - VirtualThreads: reflection-based detection and executor factory
  - VirtualThreadScheduledExecutor: virtual-thread-backed scheduled
    executor for Armeria's blockingTaskExecutor
  - Default Docker image changed to JDK 25; JDK 11/17/21 variants kept
  - Kill switch: SW_VIRTUAL_THREADS_ENABLED=false

  On JDK 25+, ~9 ForkJoinPool carrier threads replace up to 800+
  platform threads across all handler pools.

Author: wu-sheng

.github/workflows/publish-docker.yaml

@@ -75,6 +75,11 @@ jobs:
         uses: docker/setup-qemu-action@v3
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
+      - name: Build and push docker images based on Java 11
+        env:
+          SW_OAP_BASE_IMAGE: eclipse-temurin:11-jre
+          TAG: ${{ env.TAG }}-java11
+        run: make build.all docker.push
       - name: Build and push docker images based on Java 17
         env:
           SW_OAP_BASE_IMAGE: eclipse-temurin:17-jre
@@ -85,11 +90,6 @@ jobs:
           SW_OAP_BASE_IMAGE: eclipse-temurin:21-jre
           TAG: ${{ env.TAG }}-java21
         run: make build.all docker.push
-      - name: Build and push docker images based on Java 25
-        env:
-          SW_OAP_BASE_IMAGE: eclipse-temurin:25-jre
-          TAG: ${{ env.TAG }}-java25
-        run: make build.all docker.push
       - name: Build and push docker images
         run: make build.all docker.push
       - name: Build and push data-generator image

docker/oap/Dockerfile

@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-ARG BASE_IMAGE='eclipse-temurin:11-jre'
+ARG BASE_IMAGE='eclipse-temurin:25-jre'
 
 FROM $BASE_IMAGE
 

docs/en/changes/changes.md

@@ -12,6 +12,17 @@
 * Add `CLAUDE.md` as AI assistant guide for the project.
 * Upgrade Groovy to 5.0.3 in OAP backend.
 * Bump up nodejs to v24.13.0 for the latest UI(booster-ui) compiling.
+* Add virtual thread support (JDK 25+) for gRPC and Armeria HTTP server handler threads.
+  Set `SW_VIRTUAL_THREADS_ENABLED=false` to disable.
+
+  | Pool | Threads (JDK < 25) | Threads (JDK 25+) |
+  |---|---|---|
+  | gRPC server handler (`core-grpc`, `receiver-grpc`, `als-grpc`, `ebpf-grpc`) | Cached platform (unbounded) | Virtual threads |
+  | HTTP blocking (`core-http`, `receiver-http`, `promql-http`, `logql-http`, `zipkin-query-http`, `zipkin-http`, `firehose-http`) | Cached platform (max 200) | Virtual threads |
+  | VT carrier threads (ForkJoinPool) | N/A | ~9 shared |
+
+  On JDK 25+, all 11 thread pools above share ~9 carrier threads instead of up to 1,400+ platform threads.
+* Change default Docker base image to JDK 25 (`eclipse-temurin:25-jre`). JDK 11 kept as `-java11` variant.
 
 #### OAP Server
 

docs/en/setup/backend/configuration-vocabulary.md

@@ -542,6 +542,16 @@ OAP will query the data from the "hot and warm" stage by default if the "warm" s
 | property               | -               | -               | The group settings of property, such as UI and profiling.                                                                                                                            | -                                                     | -         |
 | -                      | shardNum        | -               | Shards Number for property group.                                                                                                                                                    | SW_STORAGE_BANYANDB_PROPERTY_SHARD_NUM                | 1         | 
 | -                      | replicas        | -               | Replicas for property group.                                                                                                                                                        |SW_STORAGE_BANYANDB_PROPERTY_REPLICAS                 | 0         |
+
+## Standalone Environment Variables
+The following environment variables are **not** backed by `application.yml`. They are read directly from the
+process environment and take effect across all modules.
+
+| Environment Variable              | Value(s) and Explanation                                                                                                                                                                                                                                            | Default |
+|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
+| SW_OAL_ENGINE_DEBUG               | Set to any non-empty value to dump OAL-generated `.class` files to disk (under the `oal-rt/` directory relative to the OAP working path). Useful for debugging code generation issues. Leave unset in production.                                                  | (not set, no files written) |
+| SW_VIRTUAL_THREADS_ENABLED        | Set to `false` to disable virtual threads on JDK 25+. On JDK 25+, gRPC server handler threads and HTTP blocking task executors are virtual threads by default. Set this variable to `false` to force traditional platform thread pools. Ignored on JDK versions below 25. | (not set, virtual threads enabled on JDK 25+) |
+
 ## Note
 
 ¹ System Environment Variable name could be declared and changed in `application.yml/bydb.yaml`. The names listed here are simply

oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/CoreModuleProvider.java

@@ -249,6 +249,7 @@ public void prepare() throws ServiceNotProvidedException, ModuleStartException {
         if (moduleConfig.getGRPCThreadPoolSize() > 0) {
             grpcServer.setThreadPoolSize(moduleConfig.getGRPCThreadPoolSize());
         }
+        grpcServer.setThreadPoolName("core-grpc");
         grpcServer.initialize();
 
         HTTPServerConfig httpServerConfig = HTTPServerConfig.builder()
@@ -264,6 +265,7 @@ public void prepare() throws ServiceNotProvidedException, ModuleStartException {
         setBootingParameter("oap.external.http.host", moduleConfig.getRestHost());
         setBootingParameter("oap.external.http.port", moduleConfig.getRestPort());
         httpServer = new HTTPServer(httpServerConfig);
+        httpServer.setBlockingTaskName("core-http");
         httpServer.initialize();
 
         this.registerServiceImplementation(ConfigService.class, new ConfigService(moduleConfig, this));

oap-server/server-library/library-server/src/main/java/org/apache/skywalking/oap/server/library/server/grpc/GRPCServer.java

@@ -38,6 +38,7 @@
 import org.apache.skywalking.oap.server.library.server.ServerException;
 import org.apache.skywalking.oap.server.library.server.grpc.ssl.DynamicSslContext;
 import org.apache.skywalking.oap.server.library.server.pool.CustomThreadFactory;
+import org.apache.skywalking.oap.server.library.util.VirtualThreads;
 
 @Slf4j
 public class GRPCServer implements Server {
@@ -53,6 +54,7 @@ public class GRPCServer implements Server {
     private String trustedCAsFile;
     private DynamicSslContext sslContext;
     private int threadPoolSize;
+    private String threadPoolName = "grpcServerPool";
     private static final Marker SERVER_START_MARKER = MarkerFactory.getMarker("Console");
 
     public GRPCServer(String host, int port) {
@@ -72,6 +74,10 @@ public void setThreadPoolSize(int threadPoolSize) {
         this.threadPoolSize = threadPoolSize;
     }
 
+    public void setThreadPoolName(String threadPoolName) {
+        this.threadPoolName = threadPoolName;
+    }
+
     /**
      * Require for `server.crt` and `server.pem` for open ssl at server side.
      *
@@ -96,11 +102,21 @@ public void initialize() {
         if (maxMessageSize > 0) {
             nettyServerBuilder.maxInboundMessageSize(maxMessageSize);
         }
-        if (threadPoolSize > 0) {
-            ExecutorService executor = new ThreadPoolExecutor(
-                threadPoolSize, threadPoolSize, 60, TimeUnit.SECONDS, new SynchronousQueue<>(),
-                new CustomThreadFactory("grpcServerPool"), new CustomRejectedExecutionHandler()
-            );
+        final ExecutorService executor = VirtualThreads.createExecutor(
+            threadPoolName,
+            () -> {
+                if (threadPoolSize > 0) {
+                    return new ThreadPoolExecutor(
+                        threadPoolSize, threadPoolSize, 60, TimeUnit.SECONDS,
+                        new SynchronousQueue<>(),
+                        new CustomThreadFactory(threadPoolName),
+                        new CustomRejectedExecutionHandler()
+                    );
+                }
+                return null;
+            }
+        );
+        if (executor != null) {
             nettyServerBuilder.executor(executor);
         }
 

oap-server/server-library/library-server/src/main/java/org/apache/skywalking/oap/server/library/server/http/HTTPServer.java

@@ -35,10 +35,12 @@
 import java.time.Duration;
 import java.util.List;
 import java.util.Set;
+import java.util.concurrent.ScheduledExecutorService;
 
 import lombok.extern.slf4j.Slf4j;
 import org.apache.skywalking.oap.server.library.server.Server;
 import org.apache.skywalking.oap.server.library.server.ssl.PrivateKeyUtil;
+import org.apache.skywalking.oap.server.library.util.VirtualThreads;
 
 import static java.util.Objects.requireNonNull;
 
@@ -48,11 +50,16 @@ public class HTTPServer implements Server {
     protected ServerBuilder sb;
     // Health check service, supports HEAD, GET method.
     protected final Set<HttpMethod> allowedMethods = Sets.newHashSet(HttpMethod.HEAD);
+    private String blockingTaskName = "http-blocking";
 
     public HTTPServer(HTTPServerConfig config) {
         this.config = config;
     }
 
+    public void setBlockingTaskName(final String blockingTaskName) {
+        this.blockingTaskName = blockingTaskName;
+    }
+
     @Override
     public void initialize() {
         sb = com.linecorp.armeria.server.Server
@@ -93,6 +100,14 @@ public void initialize() {
             sb.absoluteUriTransformer(this::transformAbsoluteURI);
         }
 
+        if (VirtualThreads.isSupported()) {
+            final ScheduledExecutorService blockingExecutor = VirtualThreads.createScheduledExecutor(
+                blockingTaskName, () -> null);
+            if (blockingExecutor != null) {
+                sb.blockingTaskExecutor(blockingExecutor, true);
+            }
+        }
+
         log.info("Server root context path: {}", config.getContextPath());
     }