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

This PR introduces the `rpc.system.name` and `rpc.method` span
attributes in gRPC.

To achieve this, all `Traced*Callable` classes were modified with a
constructor overload that accepts an `ApiTracerContext` instance. Such
an instance will be preferred over `SpanName` when deciding which (also
newly introduced) overload of `ApiTracerFactory.newTracer()` will be
called.

The new method in `ApiTracerFactory`, `newTracer(ApiTracer parent,
ApiTracerContext tracerContext, OperationType operationType)` will by
default merge the existing factory's context with the new one and simply
create a new `SpanName`.

However, the logic in `SpanTracerFactory` will use the context to create
the span name directly.

The `rpc.system.name` and `rpc.method` properties are obtained from
`GrpcCallableFactory` and stored in `ApiTracerContext`, which now holds
the regexes for parsing client and method names (used when building
`SpanName`s).

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: diegomarquezp

sdk-platform-java/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();
   }
 }

sdk-platform-java/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)

sdk-platform-java/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);
   }
 }

sdk-platform-java/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();
   }