feat(o11y): Introduce rpc.system.name and rpc.method in gRPC

gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/GrpcCallableFactory.java

@@ -29,13 +29,13 @@
  */
 package com.google.api.gax.grpc;
 
-import com.google.api.core.InternalApi;
 import com.google.api.gax.longrunning.OperationSnapshot;
 import com.google.api.gax.rpc.BatchingCallSettings;
 import com.google.api.gax.rpc.BidiStreamingCallable;
 import com.google.api.gax.rpc.Callables;
 import com.google.api.gax.rpc.ClientContext;
 import com.google.api.gax.rpc.ClientStreamingCallable;
+import com.google.api.gax.rpc.LibraryMetadata;
 import com.google.api.gax.rpc.LongRunningClient;
 import com.google.api.gax.rpc.OperationCallSettings;
 import com.google.api.gax.rpc.OperationCallable;
@@ -46,6 +46,7 @@
 import com.google.api.gax.rpc.StreamingCallSettings;
 import com.google.api.gax.rpc.UnaryCallSettings;
 import com.google.api.gax.rpc.UnaryCallable;
+import com.google.api.gax.tracing.ApiTracerContext;
 import com.google.api.gax.tracing.SpanName;
 import com.google.api.gax.tracing.TracedBatchingCallable;
 import com.google.api.gax.tracing.TracedBidiCallable;
@@ -54,19 +55,15 @@
 import com.google.api.gax.tracing.TracedOperationInitialCallable;
 import com.google.api.gax.tracing.TracedServerStreamingCallable;
 import com.google.api.gax.tracing.TracedUnaryCallable;
-import com.google.common.base.Preconditions;
+import com.google.common.annotations.VisibleForTesting;
 import com.google.common.collect.ImmutableSet;
 import com.google.longrunning.Operation;
 import com.google.longrunning.stub.OperationsStub;
 import io.grpc.MethodDescriptor;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
 import javax.annotation.Nonnull;
 
 /** Class with utility methods to create grpc-based direct callables. */
 public class GrpcCallableFactory {
-  // Used to extract service and method name from a grpc MethodDescriptor.
-  private static final Pattern FULL_METHOD_NAME_REGEX = Pattern.compile("^.*?([^./]+)/([^./]+)$");
 
   private GrpcCallableFactory() {}
 
@@ -112,7 +109,7 @@ public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createUna
         new TracedUnaryCallable<>(
             callable,
             clientContext.getTracerFactory(),
-            getSpanName(grpcCallSettings.getMethodDescriptor()));
+            getApiTracerContext(grpcCallSettings.getMethodDescriptor()));
 
     return callable.withDefaultCallContext(clientContext.getDefaultCallContext());
   }
@@ -161,7 +158,7 @@ public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> createBat
         new TracedBatchingCallable<>(
             baseCallable,
             clientContext.getTracerFactory(),
-            getSpanName(grpcCallSettings.getMethodDescriptor()),
+            getApiTracerContext(grpcCallSettings.getMethodDescriptor()),
             batchingCallSettings.getBatchingDescriptor());
 
     UnaryCallable<RequestT, ResponseT> batchingCallable =
@@ -187,7 +184,8 @@ OperationCallable<RequestT, ResponseT, MetadataT> createOperationCallable(
           ClientContext clientContext,
           OperationsStub operationsStub) {
 
-    SpanName initialSpanName = getSpanName(grpcCallSettings.getMethodDescriptor());
+    ApiTracerContext tracerContext = getApiTracerContext(grpcCallSettings.getMethodDescriptor());
+    SpanName initialSpanName = SpanName.of(tracerContext);
     SpanName operationSpanName =
         SpanName.of(initialSpanName.getClientName(), initialSpanName.getMethodName() + "Operation");
 
@@ -237,7 +235,7 @@ BidiStreamingCallable<RequestT, ResponseT> createBidiStreamingCallable(
         new TracedBidiCallable<>(
             callable,
             clientContext.getTracerFactory(),
-            getSpanName(grpcCallSettings.getMethodDescriptor()));
+            getApiTracerContext(grpcCallSettings.getMethodDescriptor()));
 
     return callable.withDefaultCallContext(clientContext.getDefaultCallContext());
   }
@@ -295,7 +293,7 @@ ServerStreamingCallable<RequestT, ResponseT> createServerStreamingCallable(
         new TracedServerStreamingCallable<>(
             callable,
             clientContext.getTracerFactory(),
-            getSpanName(grpcCallSettings.getMethodDescriptor()));
+            getApiTracerContext(grpcCallSettings.getMethodDescriptor()));
 
     return callable.withDefaultCallContext(clientContext.getDefaultCallContext());
   }
@@ -323,16 +321,17 @@ ClientStreamingCallable<RequestT, ResponseT> createClientStreamingCallable(
         new TracedClientStreamingCallable<>(
             callable,
             clientContext.getTracerFactory(),
-            getSpanName(grpcCallSettings.getMethodDescriptor()));
+            getApiTracerContext(grpcCallSettings.getMethodDescriptor()));
 
     return callable.withDefaultCallContext(clientContext.getDefaultCallContext());
   }
 
-  @InternalApi("Visible for testing")
-  static SpanName getSpanName(@Nonnull MethodDescriptor<?, ?> methodDescriptor) {
-    Matcher matcher = FULL_METHOD_NAME_REGEX.matcher(methodDescriptor.getFullMethodName());
-
-    Preconditions.checkArgument(matcher.matches(), "Invalid fullMethodName");
-    return SpanName.of(matcher.group(1), matcher.group(2));
+  @VisibleForTesting
+  static ApiTracerContext getApiTracerContext(@Nonnull MethodDescriptor<?, ?> methodDescriptor) {
+    return ApiTracerContext.newBuilder()
+        .setFullMethodName(methodDescriptor.getFullMethodName())
+        .setTransport(ApiTracerContext.Transport.GRPC)
+        .setLibraryMetadata(LibraryMetadata.empty())
+        .build();
   }
 }

gax-java/gax-grpc/src/test/java/com/google/api/gax/grpc/GrpcCallableFactoryTest.java

@@ -157,7 +157,7 @@ void testGetSpanName() {
             .setResponseMarshaller(Mockito.mock(Marshaller.class))
             .build();
 
-    SpanName actualSpanName = GrpcCallableFactory.getSpanName(descriptor);
+    SpanName actualSpanName = SpanName.of(GrpcCallableFactory.getApiTracerContext(descriptor));
     assertThat(actualSpanName).isEqualTo(SpanName.of("Bigtable", "ReadRows"));
   }
 
@@ -172,7 +172,7 @@ void testGetSpanNameUnqualified() {
             .setResponseMarshaller(Mockito.mock(Marshaller.class))
             .build();
 
-    SpanName actualSpanName = GrpcCallableFactory.getSpanName(descriptor);
+    SpanName actualSpanName = SpanName.of(GrpcCallableFactory.getApiTracerContext(descriptor));
     assertThat(actualSpanName).isEqualTo(SpanName.of("UnqualifiedService", "ReadRows"));
   }
 
@@ -192,7 +192,7 @@ void testGetSpanNameInvalid() {
 
       IllegalArgumentException actualError = null;
       try {
-        SpanName spanName = GrpcCallableFactory.getSpanName(descriptor);
+        SpanName spanName = SpanName.of(GrpcCallableFactory.getApiTracerContext(descriptor));
         Truth.assertWithMessage(
                 "Invalid method descriptor should not have a valid span name: %s should not generate the spanName: %s",
                 invalidName, spanName)

gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpJsonCallableFactory.java

@@ -35,6 +35,7 @@
 import com.google.api.gax.rpc.BatchingCallSettings;
 import com.google.api.gax.rpc.Callables;
 import com.google.api.gax.rpc.ClientContext;
+import com.google.api.gax.rpc.LibraryMetadata;
 import com.google.api.gax.rpc.LongRunningClient;
 import com.google.api.gax.rpc.OperationCallSettings;
 import com.google.api.gax.rpc.OperationCallable;
@@ -43,17 +44,13 @@
 import com.google.api.gax.rpc.ServerStreamingCallable;
 import com.google.api.gax.rpc.UnaryCallSettings;
 import com.google.api.gax.rpc.UnaryCallable;
+import com.google.api.gax.tracing.ApiTracerContext;
 import com.google.api.gax.tracing.SpanName;
 import com.google.api.gax.tracing.TracedUnaryCallable;
-import com.google.common.base.Preconditions;
-import java.util.regex.Matcher;
-import java.util.regex.Pattern;
 import javax.annotation.Nonnull;
 
 /** Class with utility methods to create http/json-based direct callables. */
 public class HttpJsonCallableFactory {
-  // Used to extract service and method name from a HttpJson MethodDescriptor.
-  private static final Pattern FULL_METHOD_NAME_REGEX = Pattern.compile("^.*?([^./]+)/([^./]+)$");
 
   private HttpJsonCallableFactory() {}
 
@@ -226,9 +223,12 @@ ServerStreamingCallable<RequestT, ResponseT> createServerStreamingCallable(
 
   @InternalApi("Visible for testing")
   static SpanName getSpanName(@Nonnull ApiMethodDescriptor<?, ?> methodDescriptor) {
-    Matcher matcher = FULL_METHOD_NAME_REGEX.matcher(methodDescriptor.getFullMethodName());
-
-    Preconditions.checkArgument(matcher.matches(), "Invalid fullMethodName");
-    return SpanName.of(matcher.group(1), matcher.group(2));
+    ApiTracerContext apiTracerContext =
+        ApiTracerContext.newBuilder()
+            .setFullMethodName(methodDescriptor.getFullMethodName())
+            .setTransport(ApiTracerContext.Transport.HTTP)
+            .setLibraryMetadata(LibraryMetadata.empty())
+            .build();
+    return SpanName.of(apiTracerContext);
   }
 }

gax-java/gax/src/main/java/com/google/api/gax/rpc/LibraryMetadata.java

@@ -45,16 +45,34 @@
 @AutoValue
 public abstract class LibraryMetadata {
 
+  /**
+   * Returns the repository of the client library.
+   *
+   * <p>Example: "googleapis/google-cloud-java". This maps to the {@code gcp.client.repo} attribute.
+   *
+   * @return the repository, or {@code null} if not set
+   */
   @Nullable
   public abstract String repository();
 
+  /**
+   * Returns the artifact name of the client library.
+   *
+   * <p>Example: "google-cloud-vision". This maps to the {@code gcp.client.artifact} attribute.
+   *
+   * @return the artifact name, or {@code null} if not set
+   */
   @Nullable
   public abstract String artifactName();
 
   public static LibraryMetadata empty() {
     return newBuilder().build();
   }
 
+  public boolean isEmpty() {
+    return repository() == null && artifactName() == null;
+  }
+
   public static LibraryMetadata.Builder newBuilder() {
     return new AutoValue_LibraryMetadata.Builder();
   }

gax-java/gax/src/main/java/com/google/api/gax/tracing/ApiTracerContext.java

@@ -46,19 +46,90 @@
 @InternalApi
 @AutoValue
 public abstract class ApiTracerContext {
+
+  public enum Transport {
+    GRPC("grpc"),
+    HTTP("http");
+
+    private final String label;
+
+    Transport(String label) {
+      this.label = label;
+    }
+  }
+
+  /**
+   * Returns the server address of the RPC.
+   *
+   * <p>Example: "pubsub.googleapis.com". This maps to the {@code server.address} attribute.
+   *
+   * @return the server address, or {@code null} if not set
+   */
   @Nullable
-  public abstract String serverAddress();
+  abstract String serverAddress();
 
-  public abstract LibraryMetadata libraryMetadata();
+  /**
+   * Returns the library metadata associated with the RPC.
+   *
+   * <p>See {@link LibraryMetadata} for examples of how this maps to observability attributes.
+   *
+   * @return the library metadata
+   */
+  abstract LibraryMetadata libraryMetadata();
+
+  /**
+   * Returns the RPC system name based on the transport.
+   *
+   * <p>Example: "grpc" or "http". This maps to the {@code rpc.system.name} attribute.
+   *
+   * @return the RPC system name, or {@code null} if the transport is not set
+   */
+  @Nullable
+  String rpcSystemName() {
+    if (transport() == null) {
+      return null;
+    }
+    return transport().label;
+  }
+
+  /**
+   * Returns the full name of the RPC method. Used in gRPC requests.
+   *
+   * <p>This is typically in the format "package.Service/Method"
+   *
+   * <p>Example: "google.pubsub.v1.Publisher/Publish". This maps to the {@code rpc.method}
+   * attribute.
+   *
+   * @return the full method name, or {@code null} if not set
+   */
+  @Nullable
+  abstract String fullMethodName();
+
+  /**
+   * Returns the transport protocol used for the RPC.
+   *
+   * <p>Example: {@link Transport#GRPC}. This is used to derive the {@code rpc.system.name}
+   * attribute (e.g., "grpc").
+   *
+   * @return the transport protocol, or {@code null} if not set
+   */
+  @Nullable
+  abstract Transport transport();
 
   /**
    * @return a map of attributes to be included in attempt-level spans
    */
-  public Map<String, String> getAttemptAttributes() {
+  Map<String, String> getAttemptAttributes() {
     Map<String, String> attributes = new HashMap<>();
     if (serverAddress() != null) {
       attributes.put(ObservabilityAttributes.SERVER_ADDRESS_ATTRIBUTE, serverAddress());
     }
+    if (fullMethodName() != null) {
+      attributes.put(ObservabilityAttributes.GRPC_RPC_METHOD_ATTRIBUTE, fullMethodName());
+    }
+    if (rpcSystemName() != null) {
+      attributes.put(ObservabilityAttributes.RPC_SYSTEM_NAME_ATTRIBUTE, rpcSystemName());
+    }
     if (libraryMetadata().repository() != null) {
       attributes.put(ObservabilityAttributes.REPO_ATTRIBUTE, libraryMetadata().repository());
     }
@@ -68,6 +139,29 @@ public Map<String, String> getAttemptAttributes() {
     return attributes;
   }
 
+  /**
+   * Merges this context with another context. The values in the other context take precedence.
+   *
+   * @param other the other context to merge with
+   * @return a new {@link ApiTracerContext} with merged values
+   */
+  ApiTracerContext merge(ApiTracerContext other) {
+    Builder builder = toBuilder();
+    if (other.serverAddress() != null) {
+      builder.setServerAddress(other.serverAddress());
+    }
+    if (!other.libraryMetadata().isEmpty()) {
+      builder.setLibraryMetadata(other.libraryMetadata());
+    }
+    if (other.fullMethodName() != null) {
+      builder.setFullMethodName(other.fullMethodName());
+    }
+    if (other.transport() != null) {
+      builder.setTransport(other.transport());
+    }
+    return builder.build();
+  }
+
   public static ApiTracerContext empty() {
     return newBuilder().setLibraryMetadata(LibraryMetadata.empty()).build();
   }
@@ -76,12 +170,18 @@ public static Builder newBuilder() {
     return new AutoValue_ApiTracerContext.Builder();
   }
 
+  public abstract Builder toBuilder();
+
   @AutoValue.Builder
   public abstract static class Builder {
     public abstract Builder setServerAddress(@Nullable String serverAddress);
 
     public abstract Builder setLibraryMetadata(LibraryMetadata gapicProperties);
 
+    public abstract Builder setFullMethodName(@Nullable String rpcMethod);
+
+    public abstract Builder setTransport(@Nullable Transport transport);
+
     public abstract ApiTracerContext build();
   }
 }

gax-java/gax/src/main/java/com/google/api/gax/tracing/ApiTracerFactory.java

@@ -62,6 +62,26 @@ enum OperationType {
    */
   ApiTracer newTracer(ApiTracer parent, SpanName spanName, OperationType operationType);
 
+  /**
+   * Create a new {@link ApiTracer} that will be a child of the current context.
+   *
+   * @param parent the parent of this tracer
+   * @param tracerContext the method-definition-specific tracer context
+   * @param operationType the type of operation that the tracer will trace
+   */
+  default ApiTracer newTracer(
+      ApiTracer parent, ApiTracerContext tracerContext, OperationType operationType) {
+    SpanName spanName = SpanName.of(tracerContext);
+    return newTracer(parent, spanName, operationType);
+  }
+
+  /**
+   * @return the {@link ApiTracerContext} for this factory
+   */
+  default ApiTracerContext getApiTracerContext() {
+    return ApiTracerContext.empty();
+  }
+
   /**
    * Returns a new {@link ApiTracerFactory} that will use the provided context to infer attributes
    * for all tracers created by the factory.