Add optional OpenTelemetry Netty server instrumentation

- Update lys.version to 2026.04.14

- Add optional compileOnly dependency on opentelemetry-netty-4.1 in rbcs-server

- Add runtime guard to only activate instrumentation when OTel classes are on classpath

- Insert OTel combined handler after HttpServerCodec in the Netty pipeline

- Add requires-static JPMS directives for optional module support

rbcs-server/build.gradle

@@ -13,6 +13,11 @@ dependencies {
     implementation catalog.netty.buffer
     implementation catalog.netty.transport
     implementation catalog.netty.codec.haproxy
+    compileOnly catalog.opentelemetry.netty['4']['1']
+    compileOnly catalog.opentelemetry.sdk.extension.autoconfigure
+    compileOnly catalog.opentelemetry.logback.appender['1']['0']
+    compileOnly catalog.opentelemetry.extension.trace.propagators
+    compileOnly catalog.logback.classic
 
     api project(':rbcs-common')
     api project(':rbcs-api')

rbcs-server/src/main/java/module-info.java

@@ -17,6 +17,11 @@ module net.woggioni.rbcs.server {
     requires io.netty.common;
     requires io.netty.codec;
     requires io.netty.codec.haproxy;
+    requires static io.opentelemetry.api;
+    requires static io.opentelemetry.instrumentation.netty_4_1;
+    requires static io.opentelemetry.sdk.autoconfigure;
+    requires static io.opentelemetry.instrumentation.logback_appender_1_0;
+    requires static io.opentelemetry.extension.trace.propagation;
     requires org.slf4j;
 
     exports net.woggioni.rbcs.server;

rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/RemoteBuildCacheServer.kt

@@ -2,16 +2,8 @@ package net.woggioni.rbcs.server
 
 import io.netty.bootstrap.ServerBootstrap
 import io.netty.buffer.ByteBuf
-import io.netty.channel.Channel
-import io.netty.channel.ChannelFactory
-import io.netty.channel.ChannelFuture
+import io.netty.channel.*
 import io.netty.channel.ChannelHandler.Sharable
-import io.netty.channel.ChannelHandlerContext
-import io.netty.channel.ChannelInboundHandlerAdapter
-import io.netty.channel.ChannelInitializer
-import io.netty.channel.ChannelOption
-import io.netty.channel.ChannelPromise
-import io.netty.channel.MultiThreadIoEventLoopGroup
 import io.netty.channel.nio.NioIoHandler
 import io.netty.channel.socket.DatagramChannel
 import io.netty.channel.socket.ServerSocketChannel
@@ -21,12 +13,7 @@ import io.netty.channel.socket.nio.NioServerSocketChannel
 import io.netty.channel.socket.nio.NioSocketChannel
 import io.netty.handler.codec.compression.CompressionOptions
 import io.netty.handler.codec.haproxy.HAProxyMessageDecoder
-import io.netty.handler.codec.http.DefaultHttpContent
-import io.netty.handler.codec.http.HttpContentCompressor
-import io.netty.handler.codec.http.HttpDecoderConfig
-import io.netty.handler.codec.http.HttpHeaderNames
-import io.netty.handler.codec.http.HttpRequest
-import io.netty.handler.codec.http.HttpServerCodec
+import io.netty.handler.codec.http.*
 import io.netty.handler.ssl.ClientAuth
 import io.netty.handler.ssl.SslContext
 import io.netty.handler.ssl.SslContextBuilder
@@ -37,37 +24,15 @@ import io.netty.handler.timeout.IdleStateEvent
 import io.netty.handler.timeout.IdleStateHandler
 import io.netty.util.AttributeKey
 import io.netty.util.concurrent.EventExecutorGroup
-import java.io.OutputStream
-import java.net.InetSocketAddress
-import java.nio.file.Files
-import java.nio.file.Path
-import java.security.PrivateKey
-import java.security.cert.X509Certificate
-import java.time.Duration
-import java.time.Instant
-import java.util.Arrays
-import java.util.Base64
-import java.util.concurrent.CompletableFuture
-import java.util.concurrent.Future
-import java.util.concurrent.TimeUnit
-import java.util.concurrent.TimeoutException
-import java.util.regex.Matcher
-import java.util.regex.Pattern
-import javax.naming.ldap.LdapName
-import javax.net.ssl.SSLPeerUnverifiedException
 import net.woggioni.rbcs.api.AsyncCloseable
 import net.woggioni.rbcs.api.Configuration
 import net.woggioni.rbcs.api.exception.ConfigurationException
-import net.woggioni.rbcs.common.Cidr
+import net.woggioni.rbcs.common.*
 import net.woggioni.rbcs.common.PasswordSecurity.decodePasswordHash
 import net.woggioni.rbcs.common.PasswordSecurity.hashPassword
 import net.woggioni.rbcs.common.RBCS.getTrustManager
 import net.woggioni.rbcs.common.RBCS.loadKeystore
 import net.woggioni.rbcs.common.RBCS.toUrl
-import net.woggioni.rbcs.common.Xml
-import net.woggioni.rbcs.common.createLogger
-import net.woggioni.rbcs.common.debug
-import net.woggioni.rbcs.common.info
 import net.woggioni.rbcs.server.auth.AbstractNettyHttpAuthenticator
 import net.woggioni.rbcs.server.auth.Authorizer
 import net.woggioni.rbcs.server.auth.RoleAuthorizer
@@ -78,8 +43,26 @@ import net.woggioni.rbcs.server.handler.MaxRequestSizeHandler
 import net.woggioni.rbcs.server.handler.ProxyProtocolHandler
 import net.woggioni.rbcs.server.handler.ReadTriggerDuplexHandler
 import net.woggioni.rbcs.server.handler.ServerHandler
+import net.woggioni.rbcs.server.otel.OtelSdkIntegration
 import net.woggioni.rbcs.server.throttling.BucketManager
 import net.woggioni.rbcs.server.throttling.ThrottlingHandler
+import java.io.OutputStream
+import java.net.InetSocketAddress
+import java.nio.file.Files
+import java.nio.file.Path
+import java.security.PrivateKey
+import java.security.cert.X509Certificate
+import java.time.Duration
+import java.time.Instant
+import java.util.*
+import java.util.concurrent.CompletableFuture
+import java.util.concurrent.Future
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.TimeoutException
+import java.util.regex.Matcher
+import java.util.regex.Pattern
+import javax.naming.ldap.LdapName
+import javax.net.ssl.SSLPeerUnverifiedException
 
 class RemoteBuildCacheServer(private val cfg: Configuration) {
 
@@ -431,6 +414,9 @@ class RemoteBuildCacheServer(private val cfg: Configuration) {
                 maxChunkSize = cfg.connection.chunkSize
             }
             pipeline.addLast(HttpServerCodec(httpDecoderConfig))
+            if(cfg.isEnableTelemetry) {
+                OtelSdkIntegration.createHandler().let { pipeline.addLast(it) }
+            }
             pipeline.addLast(ReadTriggerDuplexHandler.NAME, ReadTriggerDuplexHandler())
             pipeline.addLast(MaxRequestSizeHandler.NAME, MaxRequestSizeHandler(cfg.connection.maxRequestSize))
             pipeline.addLast(HttpChunkContentCompressor(1024))
@@ -525,6 +511,9 @@ class RemoteBuildCacheServer(private val cfg: Configuration) {
     }
 
     fun run(): ServerHandle {
+        if(cfg.isEnableTelemetry) {
+            OtelSdkIntegration.initialize()
+        }
         // Create the multithreaded event loops for the server
         val bossGroup = MultiThreadIoEventLoopGroup(1, NioIoHandler.newFactory())
         val channelFactory = ChannelFactory<SocketChannel> { NioSocketChannel() }

rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/configuration/Parser.kt

@@ -46,6 +46,8 @@ object Parser {
         var groups = emptyMap<String, Group>()
         var tls: Tls? = null
         val serverPath = root.renderAttribute("path")
+        var enableTelemetry = root.renderAttribute("enable-telemetry")
+            ?.let(String::toBoolean) ?: false
         var incomingConnectionsBacklogSize = 1024
         var authentication: Authentication? = null
         for (child in root.asIterable()) {
@@ -233,6 +235,7 @@ object Parser {
             }
         }
         return Configuration.of(
+            enableTelemetry,
             host,
             port,
             proxyProtocolEnabled,

rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/configuration/Serializer.kt

@@ -29,6 +29,7 @@ object Serializer {
                 ?.let { serverPath ->
                 attr("path", serverPath)
             }
+            attr("enable-telemetry", conf.isEnableTelemetry.toString())
             node("bind") {
                 attr("host", conf.host)
                 attr("port", conf.port.toString())

rbcs-server/src/main/kotlin/net/woggioni/rbcs/server/otel/OtelSdkIntegration.kt

@@ -0,0 +1,51 @@
+package net.woggioni.rbcs.server.otel
+
+import io.netty.channel.ChannelHandler
+import io.opentelemetry.api.GlobalOpenTelemetry
+import io.opentelemetry.instrumentation.netty.v4_1.NettyServerTelemetry
+import net.woggioni.rbcs.common.createLogger
+import net.woggioni.rbcs.common.info
+
+object OtelSdkIntegration {
+
+    private val log = createLogger<OtelSdkIntegration>()
+
+    private val appenderAvailable: Boolean by lazy {
+        runCatching {
+            Class.forName("io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender")
+        }.fold(
+            onSuccess = { true },
+            onFailure = {
+                log.info { "OpenTelemetry logback appender not on classpath" }
+                false
+            },
+        )
+    }
+
+    fun initialize() {
+        log.info { "Initializing OpenTelemetry SDK with auto-configuration" }
+
+        val sdk = io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk.builder()
+            .setResultAsGlobal()
+            .build()
+            .openTelemetrySdk
+
+        if (appenderAvailable) {
+            runCatching {
+                val clazz = Class.forName("io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender")
+                clazz.getMethod("install", Class.forName("io.opentelemetry.api.OpenTelemetry"))
+                    .invoke(null, sdk)
+                log.info { "OpenTelemetry logback appender installed" }
+            }.onFailure { ex ->
+                val msg = ex.localizedMessage ?: ex.javaClass.name
+                log.info { "Failed to install OpenTelemetry logback appender: $msg" }
+            }
+        }
+
+        log.info { "OpenTelemetry SDK initialized successfully" }
+    }
+
+    fun createHandler(): ChannelHandler {
+        return NettyServerTelemetry.create(GlobalOpenTelemetry.get()).createCombinedHandler()
+    }
+}

rbcs-server/src/main/resources/net/woggioni/rbcs/server/rbcs-default.xml

@@ -2,7 +2,8 @@
 <rbcs:server
              xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
              xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd"
+             enable-telemetry="false">
     <bind host="127.0.0.1" port="8080" incoming-connections-backlog-size="1024"/>
     <cache xs:type="rbcs:fileSystemCacheType" path="${sys:java.io.tmpdir}/rbcs" max-age="P7D"/>
 </rbcs:server>

rbcs-server/src/main/resources/net/woggioni/rbcs/server/schema/rbcs-server.xsd

@@ -59,6 +59,14 @@
                 </xs:documentation>
             </xs:annotation>
         </xs:attribute>
+        <xs:attribute name="enable-telemetry" type="xs:boolean" use="optional" default="false">
+            <xs:annotation>
+                <xs:documentation>
+                    Enable OpenTelemetry distributed tracing for the server.
+                    Even when enabled, telemetry only activates if OpenTelemetry classes are present on the classpath.
+                </xs:documentation>
+            </xs:annotation>
+        </xs:attribute>
     </xs:complexType>
 
     <xs:complexType name="bindType">

rbcs-server/src/test/kotlin/net/woggioni/rbcs/server/test/AbstractBasicAuthServerTest.kt

@@ -32,6 +32,7 @@ abstract class AbstractBasicAuthServerTest : AbstractServerTest() {
     override fun setUp() {
         this.cacheDir = testDir.resolve("cache")
         cfg = Configuration.of(
+            false,
             "127.0.0.1",
             getFreePort(),
             false,

rbcs-server/src/test/kotlin/net/woggioni/rbcs/server/test/AbstractTlsServerTest.kt

@@ -140,11 +140,11 @@ abstract class AbstractTlsServerTest : AbstractServerTest() {
         cfg = Configuration(
             "127.0.0.1",
             getFreePort(),
+            serverPath,
             false,
             emptyList(),
-
+            false,
             100,
-            serverPath,
             Configuration.EventExecutor(false),
             Configuration.RateLimiter(true, 0x100000, 50),
             Configuration.Connection(

rbcs-server/src/test/kotlin/net/woggioni/rbcs/server/test/NoAuthServerTest.kt

@@ -34,10 +34,11 @@ class NoAuthServerTest : AbstractServerTest() {
         cfg = Configuration(
             "127.0.0.1",
             getFreePort(),
+            serverPath,
             false,
             emptyList(),
+            false,
             100,
-            serverPath,
             Configuration.EventExecutor(false),
             Configuration.RateLimiter(true, 0x100000, 50),
             Configuration.Connection(

rbcs-server/src/test/resources/net/woggioni/rbcs/server/test/valid/rbcs-default.xml

@@ -1,7 +1,8 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <rbcs:server xmlns:xs="http://www.w3.org/2001/XMLSchema-instance"
              xmlns:rbcs="urn:net.woggioni.rbcs.server"
-             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd">
+             xs:schemaLocation="urn:net.woggioni.rbcs.server jpms://net.woggioni.rbcs.server/net/woggioni/rbcs/server/schema/rbcs-server.xsd"
+             enable-telemetry="true" path="/my/custom/path">
     <bind host="127.0.0.1" port="11443" incoming-connections-backlog-size="22" proxy-protocol="true">
         <trusted-proxies>
             <allow cidr="192.168.0.11/32"/>