feat(gax): Implement trace context extraction and injection with integration test (#12625)

This PR implements native trace context propagation for Google Cloud
Java clients, enabling App Centric Observability by linking client-side
telemetry with server-side resources.

It introduces a new injectTraceContext method to the ApiTracer interface
and implements it in SpanTracer using the OpenTelemetry
W3CTraceContextPropagator. The extracted trace context is then
dynamically injected into the outgoing request metadata natively within
GrpcClientCalls and HttpJsonClientCalls for unary requests.
CompositeTracer has also been updated to delegate this new
  method to its child tracers.

By pushing this logic down into the ApiTracer and core call factories,
we ensure that trace headers (e.g., traceparent) are automatically
propagated whenever tracing is enabled, without requiring users to
configure separate transport-specific interceptors or rely on external
OpenTelemetry instrumentation agents.

Finally, this PR includes an end-to-end integration test
(ITOtelTracePropagation) in the java-showcase module, which verifies the
successful round-trip of W3C trace headers against the gapic-showcase
server.

Author: westarle

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/GrpcClientCalls.java

@@ -90,9 +90,19 @@ public static <RequestT, ResponseT> ClientCall<RequestT, ResponseT> newCall(
       channel = ((ChannelPool) channel).getChannel(grpcContext.getChannelAffinity());
     }
 
-    if (!grpcContext.getExtraHeaders().isEmpty()) {
-      ClientInterceptor interceptor =
-          MetadataUtils.newAttachHeadersInterceptor(grpcContext.getMetadata());
+    java.util.Map<String, String> traceContext = new java.util.HashMap<>();
+    grpcContext.getTracer().injectTraceContext(traceContext);
+
+    if (!grpcContext.getExtraHeaders().isEmpty() || !traceContext.isEmpty()) {
+      Metadata metadata = new Metadata();
+      metadata.merge(grpcContext.getMetadata());
+      for (java.util.Map.Entry<String, String> entry : traceContext.entrySet()) {
+        Metadata.Key<String> key =
+            Metadata.Key.of(entry.getKey(), Metadata.ASCII_STRING_MARSHALLER);
+        metadata.removeAll(key);
+        metadata.put(key, entry.getValue());
+      }
+      ClientInterceptor interceptor = MetadataUtils.newAttachHeadersInterceptor(metadata);
       channel = ClientInterceptors.intercept(channel, interceptor);
     }
 

sdk-platform-java/gax-java/gax-grpc/src/test/java/com/google/api/gax/grpc/GrpcClientCallsTest.java

@@ -340,4 +340,48 @@ void testUniverseDomainNotReady_shouldRetry() throws IOException {
     Truth.assertThat(exception.isRetryable()).isTrue();
     Mockito.verify(mockChannel, Mockito.never()).newCall(descriptor, callOptions);
   }
+
+  @Test
+  void testTraceContextHeaders() throws IOException {
+    Metadata emptyHeaders = new Metadata();
+
+    MethodDescriptor<Color, Money> descriptor = FakeServiceGrpc.METHOD_RECOGNIZE;
+
+    @SuppressWarnings("unchecked")
+    ClientCall<Color, Money> mockClientCall = Mockito.mock(ClientCall.class);
+
+    @SuppressWarnings("unchecked")
+    ClientCall.Listener<Money> mockListener = Mockito.mock(ClientCall.Listener.class);
+
+    Channel mockChannel = Mockito.mock(ManagedChannel.class);
+    com.google.api.gax.tracing.ApiTracer mockTracer =
+        Mockito.mock(com.google.api.gax.tracing.ApiTracer.class);
+
+    Mockito.doAnswer(
+            invocation -> {
+              java.util.Map<String, String> carrier = invocation.getArgument(0);
+              carrier.put("traceparent", "00-00000000000000000000000000000001-0000000000000002-01");
+              return null;
+            })
+        .when(mockTracer)
+        .injectTraceContext(Mockito.anyMap());
+
+    Mockito.doAnswer(
+            invocation -> {
+              Metadata clientCallHeaders = (Metadata) invocation.getArguments()[1];
+              Metadata.Key<String> traceparentKey =
+                  Metadata.Key.of("traceparent", Metadata.ASCII_STRING_MARSHALLER);
+              assertThat(clientCallHeaders.getAll(traceparentKey))
+                  .containsExactly("00-00000000000000000000000000000001-0000000000000002-01");
+              return null;
+            })
+        .when(mockClientCall)
+        .start(Mockito.<ClientCall.Listener<Money>>any(), Mockito.<Metadata>any());
+
+    Mockito.when(mockChannel.newCall(Mockito.eq(descriptor), Mockito.<CallOptions>any()))
+        .thenReturn(mockClientCall);
+
+    GrpcCallContext context = defaultCallContext.withChannel(mockChannel).withTracer(mockTracer);
+    GrpcClientCalls.newCall(descriptor, context).start(mockListener, emptyHeaders);
+  }
 }

sdk-platform-java/gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/HttpJsonClientCalls.java

@@ -80,15 +80,25 @@ public static <RequestT, ResponseT> HttpJsonClientCall<RequestT, ResponseT> newC
     return httpJsonContext.getChannel().newCall(methodDescriptor, httpJsonContext.getCallOptions());
   }
 
+  static HttpJsonMetadata getMetadataWithTraceContext(HttpJsonCallContext context) {
+    java.util.Map<String, String> traceHeaders = new java.util.HashMap<>();
+    context.getTracer().injectTraceContext(traceHeaders);
+
+    java.util.Map<String, java.util.List<String>> finalHeaders =
+        new java.util.HashMap<>(context.getExtraHeaders());
+    for (java.util.Map.Entry<String, String> entry : traceHeaders.entrySet()) {
+      finalHeaders.put(entry.getKey(), java.util.Collections.singletonList(entry.getValue()));
+    }
+    return HttpJsonMetadata.newBuilder().build().withHeaders(finalHeaders);
+  }
+
   static <RequestT, ResponseT> ApiFuture<ResponseT> futureUnaryCall(
       HttpJsonClientCall<RequestT, ResponseT> clientCall,
       RequestT request,
       HttpJsonCallContext context) {
     // Start the call
     HttpJsonFuture<ResponseT> future = new HttpJsonFuture<>(clientCall);
-    clientCall.start(
-        new FutureListener<>(future),
-        HttpJsonMetadata.newBuilder().build().withHeaders(context.getExtraHeaders()));
+    clientCall.start(new FutureListener<>(future), getMetadataWithTraceContext(context));
 
     // Send the request
     try {

sdk-platform-java/gax-java/gax-httpjson/src/test/java/com/google/api/gax/httpjson/HttpJsonClientCallsTest.java

@@ -139,4 +139,35 @@ void testUniverseDomainNotReady_shouldRetry() throws IOException {
         .isEqualTo(HttpJsonStatusCode.Code.UNAUTHENTICATED);
     Mockito.verify(mockChannel, Mockito.never()).newCall(descriptor, callOptions);
   }
+
+  @Test
+  void testGetMetadataWithTraceContext() {
+    com.google.api.gax.tracing.ApiTracer mockTracer =
+        Mockito.mock(com.google.api.gax.tracing.ApiTracer.class);
+    Mockito.doAnswer(
+            invocation -> {
+              java.util.Map<String, String> carrier = invocation.getArgument(0);
+              carrier.put("traceparent", "00-00000000000000000000000000000001-0000000000000002-01");
+              return null;
+            })
+        .when(mockTracer)
+        .injectTraceContext(Mockito.anyMap());
+
+    java.util.Map<String, java.util.List<String>> extraHeaders = new java.util.HashMap<>();
+    extraHeaders.put("existing-header", java.util.Collections.singletonList("existing-value"));
+
+    HttpJsonCallContext context =
+        (HttpJsonCallContext)
+            HttpJsonCallContext.createDefault()
+                .withTracer(mockTracer)
+                .withExtraHeaders(extraHeaders);
+
+    HttpJsonMetadata metadata = HttpJsonClientCalls.getMetadataWithTraceContext(context);
+
+    assertThat(metadata.getHeaders()).containsKey("existing-header");
+    assertThat(metadata.getHeaders().get("existing-header").toString()).contains("existing-value");
+    assertThat(metadata.getHeaders()).containsKey("traceparent");
+    assertThat(metadata.getHeaders().get("traceparent").toString())
+        .contains("00-00000000000000000000000000000001-0000000000000002-01");
+  }
 }

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/tracing/ApiTracer.java

@@ -196,6 +196,9 @@ default void requestSent() {}
   default void batchRequestSent(long elementCount, long requestSize) {}
   ;
 
+  /** Extract the trace context from the tracer and add it to the given headers map. */
+  default void injectTraceContext(java.util.Map<String, String> carrier) {}
+
   /**
    * Annotates the attempt with the full resolved HTTP URL. Only relevant for HTTP transport.
    *

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/tracing/CompositeTracer.java

@@ -213,4 +213,11 @@ public void batchRequestSent(long elementCount, long requestSize) {
       child.batchRequestSent(elementCount, requestSize);
     }
   }
+
+  @Override
+  public void injectTraceContext(java.util.Map<String, String> carrier) {
+    for (ApiTracer child : children) {
+      child.injectTraceContext(carrier);
+    }
+  }
 }

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/tracing/SpanTracer.java

@@ -54,6 +54,23 @@ public class SpanTracer implements ApiTracer {
   private final ApiTracerContext apiTracerContext;
   private Span attemptSpan;
 
+  @Override
+  public void injectTraceContext(java.util.Map<String, String> carrier) {
+    if (attemptSpan != null) {
+      io.opentelemetry.context.Context context =
+          io.opentelemetry.context.Context.current().with(attemptSpan);
+      io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator.getInstance()
+          .inject(
+              context,
+              carrier,
+              (c, k, v) -> {
+                if (c != null) {
+                  c.put(k, v);
+                }
+              });
+    }
+  }
+
   /**
    * Creates a new instance of {@code SpanTracer}.
    *

sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/tracing/CompositeTracerTest.java

@@ -270,4 +270,13 @@ void testBatchRequestSent() {
     verify(child1).batchRequestSent(10L, 100L);
     verify(child2).batchRequestSent(10L, 100L);
   }
+
+  @Test
+  void testInjectTraceContext() {
+    java.util.Map<String, String> carrier = new java.util.HashMap<>();
+    compositeTracer.injectTraceContext(carrier);
+    InOrder inOrder = inOrder(child1, child2);
+    inOrder.verify(child1).injectTraceContext(carrier);
+    inOrder.verify(child2).injectTraceContext(carrier);
+  }
 }

sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/tracing/SpanTracerTest.java

@@ -602,4 +602,27 @@ public RedirectException(String message) {
   }
 
   private static class UnknownClientException extends RuntimeException {}
+
+  @Test
+  void testInjectTraceContext_addsHeaders() {
+    io.opentelemetry.api.trace.SpanContext mockSpanContext =
+        io.opentelemetry.api.trace.SpanContext.create(
+            "00000000000000000000000000000001",
+            "0000000000000002",
+            io.opentelemetry.api.trace.TraceFlags.getSampled(),
+            io.opentelemetry.api.trace.TraceState.getDefault());
+    io.opentelemetry.api.trace.Span realSpan =
+        io.opentelemetry.api.trace.Span.wrap(mockSpanContext);
+    when(spanBuilder.startSpan()).thenReturn(realSpan);
+
+    spanTracer = new SpanTracer(tracer, ApiTracerContext.empty(), ATTEMPT_SPAN_NAME);
+    spanTracer.attemptStarted(new Object(), 1);
+
+    java.util.Map<String, String> carrier = new java.util.HashMap<>();
+    spanTracer.injectTraceContext(carrier);
+
+    assertThat(carrier).containsKey("traceparent");
+    assertThat(carrier.get("traceparent")).contains("00000000000000000000000000000001");
+    assertThat(carrier.get("traceparent")).contains("0000000000000002");
+  }
 }

sdk-platform-java/java-showcase/gapic-showcase/pom.xml

@@ -17,7 +17,7 @@
   </parent>
 
   <properties>
-    <gapic-showcase.version>0.36.2</gapic-showcase.version>
+    <gapic-showcase.version>0.39.0</gapic-showcase.version>
     <!-- This is the last version supporting slf4j 1.x, do not upgrade -->
     <slf4j1-logback.version>1.2.13</slf4j1-logback.version>
     <slf4j2-logback.version>1.5.25</slf4j2-logback.version>