feat(sdk-platform-java): Add CompositeTracer and CompositeTracerFactory. (#12321)

This PR 

- Introduces CompositeTracer and CompositeTracerFactory into the
gax-java tracing architecture, enabling the delegation of telemetry,
logging, and metrics events to multiple underlying ApiTracer instances.

- Creates a LoggingTracerFactory if logging is enabled in ClientContext.

Author: blakeli0

sdk-platform-java/gax-java/gax/pom.xml

@@ -139,7 +139,7 @@
         <configuration>
           <argLine>@{argLine} -Djava.util.logging.SimpleFormatter.format="%1$tY %1$tl:%1$tM:%1$tS.%1$tL %2$s %4$s: %5$s%6$s%n"</argLine>
           <!-- These tests require an Env Var to be set. Use -PenvVarTest to ONLY run these tests -->
-          <test>!EndpointContextTest#endpointContextBuild_universeDomainEnvVarSet+endpointContextBuild_multipleUniverseDomainConfigurations_clientSettingsHasPriority,!LoggingEnabledTest,!LoggingTracerTest</test>
+          <test>!EndpointContextTest#endpointContextBuild_universeDomainEnvVarSet+endpointContextBuild_multipleUniverseDomainConfigurations_clientSettingsHasPriority,!LoggingEnabledTest,!LoggingTracerTest,!ClientContextTest#testGetApiTracerFactory_loggingEnabled</test>
         </configuration>
       </plugin>
     </plugins>
@@ -154,7 +154,7 @@
             <groupId>org.apache.maven.plugins</groupId>
             <artifactId>maven-surefire-plugin</artifactId>
             <configuration>
-              <test>EndpointContextTest#endpointContextBuild_universeDomainEnvVarSet+endpointContextBuild_multipleUniverseDomainConfigurations_clientSettingsHasPriority,LoggingEnabledTest,LoggingTracerTest</test>
+              <test>EndpointContextTest#endpointContextBuild_universeDomainEnvVarSet+endpointContextBuild_multipleUniverseDomainConfigurations_clientSettingsHasPriority,LoggingEnabledTest,LoggingTracerTest, ClientContextTest#testGetApiTracerFactory_loggingEnabled</test>
             </configuration>
           </plugin>
         </plugins>

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/logging/LoggingUtils.java

@@ -36,7 +36,7 @@
 @InternalApi
 public class LoggingUtils {
 
-  static final String GOOGLE_SDK_JAVA_LOGGING = "GOOGLE_SDK_JAVA_LOGGING";
+  private static final String GOOGLE_SDK_JAVA_LOGGING = "GOOGLE_SDK_JAVA_LOGGING";
 
   private static boolean loggingEnabled = checkLoggingEnabled(GOOGLE_SDK_JAVA_LOGGING);
 
@@ -45,7 +45,7 @@ public class LoggingUtils {
    *
    * @return true if logging is enabled, false otherwise.
    */
-  static boolean isLoggingEnabled() {
+  public static boolean isLoggingEnabled() {
     return loggingEnabled;
   }
 

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/rpc/ClientContext.java

@@ -40,11 +40,13 @@
 import com.google.api.gax.core.BackgroundResource;
 import com.google.api.gax.core.ExecutorAsBackgroundResource;
 import com.google.api.gax.core.ExecutorProvider;
+import com.google.api.gax.logging.LoggingUtils;
 import com.google.api.gax.rpc.internal.QuotaProjectIdHidingCredentials;
 import com.google.api.gax.tracing.ApiTracerContext;
 import com.google.api.gax.tracing.ApiTracerFactory;
 import com.google.api.gax.tracing.BaseApiTracerFactory;
-import com.google.api.gax.tracing.SpanTracerFactory;
+import com.google.api.gax.tracing.CompositeTracerFactory;
+import com.google.api.gax.tracing.LoggingTracerFactory;
 import com.google.auth.ApiKeyCredentials;
 import com.google.auth.CredentialTypeForMetrics;
 import com.google.auth.Credentials;
@@ -279,18 +281,7 @@ public static ClientContext create(StubSettings settings) throws IOException {
       backgroundResources.add(watchdog);
     }
 
-    ApiTracerContext apiTracerContext =
-        ApiTracerContext.newBuilder()
-            .setServerAddress(endpointContext.resolvedServerAddress())
-            .setServerPort(endpointContext.resolvedServerPort())
-            .setLibraryMetadata(settings.getLibraryMetadata())
-            .setUrlDomain(endpointContext.getUrlDomain())
-            .setServiceName(endpointContext.serviceName())
-            .build();
-    ApiTracerFactory apiTracerFactory = settings.getTracerFactory();
-    if (apiTracerFactory instanceof SpanTracerFactory) {
-      apiTracerFactory = apiTracerFactory.withContext(apiTracerContext);
-    }
+    ApiTracerFactory apiTracerFactory = getApiTracerFactory(settings, endpointContext);
 
     return newBuilder()
         .setBackgroundResources(backgroundResources.build())
@@ -311,6 +302,32 @@ public static ClientContext create(StubSettings settings) throws IOException {
         .build();
   }
 
+  @VisibleForTesting
+  static ApiTracerFactory getApiTracerFactory(
+      StubSettings settings, EndpointContext endpointContext) {
+    ApiTracerFactory apiTracerFactory = settings.getTracerFactory();
+
+    if (LoggingUtils.isLoggingEnabled()) {
+      apiTracerFactory =
+          new CompositeTracerFactory(
+              ImmutableList.of(new LoggingTracerFactory(), apiTracerFactory));
+    }
+
+    if (apiTracerFactory.needsContext()) {
+      ApiTracerContext apiTracerContext =
+          ApiTracerContext.newBuilder()
+              .setServerAddress(endpointContext.resolvedServerAddress())
+              .setServerPort(endpointContext.resolvedServerPort())
+              .setServiceName(endpointContext.serviceName())
+              .setLibraryMetadata(settings.getLibraryMetadata())
+              .setUrlDomain(endpointContext.getUrlDomain())
+              .build();
+      apiTracerFactory = apiTracerFactory.withContext(apiTracerContext);
+    }
+
+    return apiTracerFactory;
+  }
+
   /** Determines which credentials to use. API key overrides credentials provided by provider. */
   private static Credentials getCredentials(StubSettings settings) throws IOException {
     Credentials credentials;

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

@@ -74,10 +74,14 @@ default ApiTracer newTracer(ApiTracer parent, ApiTracerContext tracerContext) {
   }
 
   /**
-   * @return the {@link ApiTracerContext} for this factory
+   * Indicates whether this factory requires an {@link ApiTracerContext} to be injected via {@link
+   * #withContext(ApiTracerContext)} before creating tracers.
+   *
+   * @return {@code true} if an {@link ApiTracerContext} should be injected, {@code false}
+   *     otherwise.
    */
-  default ApiTracerContext getApiTracerContext() {
-    return ApiTracerContext.empty();
+  default boolean needsContext() {
+    return false;
   }
 
   /**

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

@@ -0,0 +1,216 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google LLC nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.google.api.gax.tracing;
+
+import com.google.api.core.InternalApi;
+import com.google.common.collect.ImmutableList;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A composite implementation of {@link ApiTracer} that delegates all tracing events to a list of
+ * underlying tracers.
+ *
+ * <p>For internal use only.
+ */
+@InternalApi
+class CompositeTracer extends BaseApiTracer {
+  private final List<ApiTracer> children;
+
+  public CompositeTracer(List<ApiTracer> children) {
+    this.children = ImmutableList.copyOf(children);
+  }
+
+  @Override
+  public Scope inScope() {
+    final List<Scope> childScopes = new ArrayList<>(children.size());
+
+    try {
+      for (ApiTracer child : children) {
+        childScopes.add(child.inScope());
+      }
+    } catch (RuntimeException e) {
+      for (int i = childScopes.size() - 1; i >= 0; i--) {
+        try {
+          childScopes.get(i).close();
+        } catch (RuntimeException suppressed) {
+          e.addSuppressed(suppressed);
+        }
+      }
+      throw e;
+    }
+
+    return () -> {
+      RuntimeException exception = null;
+      for (int i = childScopes.size() - 1; i >= 0; i--) {
+        try {
+          childScopes.get(i).close();
+        } catch (RuntimeException e) {
+          if (exception == null) {
+            exception = e;
+          } else {
+            exception.addSuppressed(e);
+          }
+        }
+      }
+      if (exception != null) {
+        throw exception;
+      }
+    };
+  }
+
+  @Override
+  public void operationSucceeded() {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).operationSucceeded();
+    }
+  }
+
+  @Override
+  public void operationCancelled() {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).operationCancelled();
+    }
+  }
+
+  @Override
+  public void operationFailed(Throwable error) {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).operationFailed(error);
+    }
+  }
+
+  @Override
+  public void connectionSelected(String id) {
+    for (ApiTracer child : children) {
+      child.connectionSelected(id);
+    }
+  }
+
+  @Override
+  @Deprecated
+  public void attemptStarted(int attemptNumber) {
+    for (ApiTracer child : children) {
+      child.attemptStarted(attemptNumber);
+    }
+  }
+
+  @Override
+  public void attemptStarted(Object request, int attemptNumber) {
+    for (ApiTracer child : children) {
+      child.attemptStarted(request, attemptNumber);
+    }
+  }
+
+  @Override
+  public void attemptSucceeded() {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).attemptSucceeded();
+    }
+  }
+
+  @Override
+  public void attemptCancelled() {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).attemptCancelled();
+    }
+  }
+
+  @Override
+  public void attemptFailed(Throwable error, org.threeten.bp.Duration delay) {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).attemptFailed(error, delay);
+    }
+  }
+
+  @Override
+  public void attemptFailedDuration(Throwable error, java.time.Duration delay) {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).attemptFailedDuration(error, delay);
+    }
+  }
+
+  @Override
+  public void attemptFailedRetriesExhausted(Throwable error) {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).attemptFailedRetriesExhausted(error);
+    }
+  }
+
+  @Override
+  public void attemptPermanentFailure(Throwable error) {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).attemptPermanentFailure(error);
+    }
+  }
+
+  @Override
+  public void lroStartFailed(Throwable error) {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).lroStartFailed(error);
+    }
+  }
+
+  @Override
+  public void lroStartSucceeded() {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).lroStartSucceeded();
+    }
+  }
+
+  @Override
+  public void responseReceived() {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).responseReceived();
+    }
+  }
+
+  @Override
+  public void responseHeadersReceived(Map<String, Object> headers) {
+    for (int i = children.size() - 1; i >= 0; i--) {
+      children.get(i).responseHeadersReceived(headers);
+    }
+  }
+
+  @Override
+  public void requestSent() {
+    for (ApiTracer child : children) {
+      child.requestSent();
+    }
+  }
+
+  @Override
+  public void batchRequestSent(long elementCount, long requestSize) {
+    for (ApiTracer child : children) {
+      child.batchRequestSent(elementCount, requestSize);
+    }
+  }
+}