Capture gRPC UNKNOWN requests

Author: trask

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### ⚠️ Breaking changes to non-stable APIs
+
+- `GrpcRequest.getMethod()` now returns `@Nullable` to support unregistered-service requests where
+  no `MethodDescriptor` is available
+  ([#16214](https://github.com/open-telemetry/opentelemetry-java-instrumentation/pull/16214))
+
 ## Version 2.25.0 (2026-02-13)
 
 ### ⚠️ Breaking changes to non-stable APIs

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcAttributesGetter.java

@@ -68,6 +68,15 @@ default String getRpcMethod(REQUEST request) {
     return null;
   }
 
+  /**
+   * Returns the original method name when the method reported via {@link #getRpcMethod(REQUEST)} is
+   * set to {@code _OTHER} because the method is not recognized by the RPC framework.
+   */
+  @Nullable
+  default String getRpcMethodOriginal(REQUEST request) {
+    return null;
+  }
+
   /**
    * Returns a description of a class of error the operation ended with.
    *

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/rpc/RpcCommonAttributesExtractor.java

@@ -19,6 +19,8 @@ abstract class RpcCommonAttributesExtractor<REQUEST, RESPONSE>
     implements AttributesExtractor<REQUEST, RESPONSE> {
 
   static final AttributeKey<String> RPC_METHOD = AttributeKey.stringKey("rpc.method");
+  static final AttributeKey<String> RPC_METHOD_ORIGINAL =
+      AttributeKey.stringKey("rpc.method_original");
 
   // Stable semconv keys
   static final AttributeKey<String> RPC_SYSTEM_NAME = AttributeKey.stringKey("rpc.system.name");
@@ -42,6 +44,7 @@ public final void onStart(AttributesBuilder attributes, Context parentContext, R
     if (emitStableRpcSemconv()) {
       attributes.put(RPC_SYSTEM_NAME, getter.getRpcSystemName(request));
       attributes.put(RPC_METHOD, getter.getRpcMethod(request));
+      attributes.put(RPC_METHOD_ORIGINAL, getter.getRpcMethodOriginal(request));
     }
 
     if (emitOldRpcSemconv()) {

instrumentation/armeria/armeria-grpc-1.14/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/armeria/grpc/v1_14/ArmeriaGrpcServiceBuilderInstrumentation.java

@@ -12,6 +12,7 @@
 import com.linecorp.armeria.server.grpc.GrpcServiceBuilder;
 import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.instrumentation.grpc.v1_6.GrpcTelemetry;
+import io.opentelemetry.instrumentation.grpc.v1_6.internal.Internal;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeInstrumentation;
 import io.opentelemetry.javaagent.extension.instrumentation.TypeTransformer;
 import net.bytebuddy.asm.Advice;
@@ -36,7 +37,8 @@ public static class BuildAdvice {
 
     @Advice.OnMethodEnter
     public static void onEnter(@Advice.This GrpcServiceBuilder builder) {
-      builder.intercept(GrpcTelemetry.create(GlobalOpenTelemetry.get()).createServerInterceptor());
+      GrpcTelemetry telemetry = GrpcTelemetry.create(GlobalOpenTelemetry.get());
+      builder.intercept(Internal.createServerInterceptor(telemetry));
     }
   }
 }

instrumentation/grpc-1.6/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/grpc/v1_6/GrpcServerBuilderInstrumentation.java

@@ -50,7 +50,7 @@ public static CallDepth onEnter(@Advice.This ServerBuilder<?> serverBuilder) {
         return callDepth;
       }
       if (!Boolean.TRUE.equals(SERVER_BUILDER_INSTRUMENTED.get(serverBuilder))) {
-        serverBuilder.intercept(GrpcSingletons.SERVER_INTERCEPTOR);
+        GrpcSingletons.configureServerBuilder(serverBuilder);
         SERVER_BUILDER_INSTRUMENTED.set(serverBuilder, true);
       }
       return callDepth;

instrumentation/grpc-1.6/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/grpc/v1_6/GrpcSingletons.java

@@ -11,7 +11,6 @@
 import io.grpc.Context;
 import io.grpc.ManagedChannelBuilder;
 import io.grpc.ServerBuilder;
-import io.grpc.ServerInterceptor;
 import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.api.incubator.config.DeclarativeConfigProperties;
 import io.opentelemetry.instrumentation.api.incubator.config.internal.DeclarativeConfigUtil;
@@ -33,7 +32,7 @@ public final class GrpcSingletons {
 
   public static final ClientInterceptor CLIENT_INTERCEPTOR;
 
-  public static final ServerInterceptor SERVER_INTERCEPTOR;
+  private static final GrpcTelemetry GRPC_TELEMETRY;
 
   private static final AtomicReference<Context.Storage> STORAGE_REFERENCE = new AtomicReference<>();
 
@@ -56,16 +55,15 @@ public final class GrpcSingletons {
             .get("server")
             .getScalarList("request", String.class, emptyList());
 
-    GrpcTelemetry telemetry =
+    GRPC_TELEMETRY =
         GrpcTelemetry.builder(GlobalOpenTelemetry.get())
             .setEmitMessageEvents(emitMessageEvents)
             .setCaptureExperimentalSpanAttributes(experimentalSpanAttributes)
             .setCapturedClientRequestMetadata(clientRequestMetadata)
             .setCapturedServerRequestMetadata(serverRequestMetadata)
             .build();
 
-    CLIENT_INTERCEPTOR = telemetry.createClientInterceptor();
-    SERVER_INTERCEPTOR = telemetry.createServerInterceptor();
+    CLIENT_INTERCEPTOR = GRPC_TELEMETRY.createClientInterceptor();
   }
 
   public static Context.Storage getStorage() {
@@ -77,5 +75,9 @@ public static Context.Storage setStorage(Context.Storage storage) {
     return getStorage();
   }
 
+  public static void configureServerBuilder(ServerBuilder<?> serverBuilder) {
+    GRPC_TELEMETRY.configureServerBuilder(serverBuilder);
+  }
+
   private GrpcSingletons() {}
 }

instrumentation/grpc-1.6/library/README.md

@@ -37,9 +37,9 @@ void configureClientInterceptor(OpenTelemetry openTelemetry, NettyChannelBuilder
   nettyChannelBuilder.intercept(grpcTelemetry.createClientInterceptor());
 }
 
-// For server-side, attatch the interceptor to your service.
-ServerServiceDefinition configureServerInterceptor(OpenTelemetry openTelemetry, ServerServiceDefinition serviceDefinition) {
+// For server-side, configure the server builder.
+void configureServer(OpenTelemetry openTelemetry, ServerBuilder<?> serverBuilder) {
   GrpcTelemetry grpcTelemetry = GrpcTelemetry.create(openTelemetry);
-  return ServerInterceptors.intercept(serviceDefinition, grpcTelemetry.createServerInterceptor());
+  grpcTelemetry.configureServerBuilder(serverBuilder);
 }
 ```

instrumentation/grpc-1.6/library/src/main/java/io/opentelemetry/instrumentation/grpc/v1_6/GrpcRequest.java

@@ -12,7 +12,9 @@
 
 public final class GrpcRequest {
 
-  private final MethodDescriptor<?, ?> method;
+  @Nullable private volatile MethodDescriptor<?, ?> method;
+  private final String fullMethodName;
+  @Nullable private final String originalFullMethodName;
 
   @Nullable private volatile Metadata metadata;
 
@@ -29,11 +31,19 @@ public final class GrpcRequest {
       @Nullable SocketAddress peerSocketAddress,
       @Nullable String authority) {
     this.method = method;
+    this.fullMethodName = method.getFullMethodName();
+    this.originalFullMethodName = null;
     this.metadata = metadata;
     this.peerSocketAddress = peerSocketAddress;
     setLogicalAddress(authority);
   }
 
+  GrpcRequest(String fullMethodName, @Nullable String originalFullMethodName, Metadata metadata) {
+    this.fullMethodName = fullMethodName;
+    this.originalFullMethodName = originalFullMethodName;
+    this.metadata = metadata;
+  }
+
   private void setLogicalAddress(@Nullable String authority) {
     if (authority == null) {
       return;
@@ -51,10 +61,20 @@ private void setLogicalAddress(@Nullable String authority) {
     }
   }
 
+  @Nullable
   public MethodDescriptor<?, ?> getMethod() {
     return method;
   }
 
+  String getFullMethodName() {
+    return fullMethodName;
+  }
+
+  @Nullable
+  String getOriginalFullMethodName() {
+    return originalFullMethodName;
+  }
+
   @Nullable
   public Metadata getMetadata() {
     return metadata;

instrumentation/grpc-1.6/library/src/main/java/io/opentelemetry/instrumentation/grpc/v1_6/GrpcRpcAttributesGetter.java

@@ -26,7 +26,7 @@ public String getSystem(GrpcRequest request) {
   @Override
   @Nullable
   public String getService(GrpcRequest request) {
-    String fullMethodName = request.getMethod().getFullMethodName();
+    String fullMethodName = request.getFullMethodName();
     int slashIndex = fullMethodName.lastIndexOf('/');
     if (slashIndex == -1) {
       return null;
@@ -38,7 +38,7 @@ public String getService(GrpcRequest request) {
   @Override
   @Nullable
   public String getMethod(GrpcRequest request) {
-    String fullMethodName = request.getMethod().getFullMethodName();
+    String fullMethodName = request.getFullMethodName();
     int slashIndex = fullMethodName.lastIndexOf('/');
     if (slashIndex == -1) {
       return null;
@@ -47,8 +47,9 @@ public String getMethod(GrpcRequest request) {
   }
 
   @Override
+  @Nullable
   public String getRpcMethod(GrpcRequest request) {
-    return request.getMethod().getFullMethodName();
+    return request.getFullMethodName();
   }
 
   @Override
@@ -63,6 +64,12 @@ public Long getResponseSize(GrpcRequest request) {
     return request.getResponseSize();
   }
 
+  @Override
+  @Nullable
+  public String getRpcMethodOriginal(GrpcRequest request) {
+    return request.getOriginalFullMethodName();
+  }
+
   List<String> metadataValue(GrpcRequest request, String key) {
     if (request.getMetadata() == null) {
       return emptyList();

instrumentation/grpc-1.6/library/src/main/java/io/opentelemetry/instrumentation/grpc/v1_6/GrpcSpanNameExtractor.java

@@ -11,6 +11,6 @@
 final class GrpcSpanNameExtractor implements SpanNameExtractor<GrpcRequest> {
   @Override
   public String extract(GrpcRequest request) {
-    return request.getMethod().getFullMethodName();
+    return request.getFullMethodName();
   }
 }