feat(observability): add no-op implementation of tracing

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

@@ -46,9 +46,14 @@
 import com.google.api.gax.core.NoCredentialsProvider;
 import com.google.api.gax.tracing.ApiTracerFactory;
 import com.google.api.gax.tracing.BaseApiTracerFactory;
+import com.google.api.gax.tracing.CompositeApiTracerFactory;
+import com.google.api.gax.tracing.OpenTelemetryTracingRecorder;
+import com.google.api.gax.tracing.TracingTracerFactory;
+import com.google.api.gax.tracing.TracingUtils;
 import com.google.auth.oauth2.QuotaProjectIdProvider;
 import com.google.common.base.MoreObjects;
 import com.google.common.base.Preconditions;
+import io.opentelemetry.api.GlobalOpenTelemetry;
 import java.io.IOException;
 import java.util.concurrent.Executor;
 import javax.annotation.Nonnull;
@@ -104,13 +109,26 @@ protected StubSettings(Builder builder) {
     this.quotaProjectId = builder.quotaProjectId;
     this.streamWatchdogProvider = builder.streamWatchdogProvider;
     this.streamWatchdogCheckInterval = builder.streamWatchdogCheckInterval;
-    this.tracerFactory = builder.tracerFactory;
+    this.tracerFactory = autoConfigureTracerFactory(builder.tracerFactory);
     this.deprecatedExecutorProviderSet = builder.deprecatedExecutorProviderSet;
     this.gdchApiAudience = builder.gdchApiAudience;
     this.endpointContext = buildEndpointContext(builder);
     this.apiKey = builder.apiKey;
   }
 
+  private ApiTracerFactory autoConfigureTracerFactory(ApiTracerFactory factory) {
+    if (TracingUtils.isTracingEnabled()) {
+      ApiTracerFactory tracingFactory =
+          new TracingTracerFactory(
+              new OpenTelemetryTracingRecorder(GlobalOpenTelemetry.get(), getServiceName()));
+      if (factory instanceof BaseApiTracerFactory) {
+        return tracingFactory;
+      }
+      return CompositeApiTracerFactory.of(factory, tracingFactory);
+    }
+    return factory;
+  }
+
   /**
    * Attempt to build the EndpointContext from the Builder based on all the user configurations
    * passed in.

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

@@ -0,0 +1,132 @@
+/*
+ * 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.List;
+import java.util.stream.Collectors;
+
+/** A composite implementation of {@link ApiTracer} that broadcasts events to multiple tracers. */
+@InternalApi
+public class CompositeApiTracer implements ApiTracer {
+  private final List<ApiTracer> tracers;
+
+  public CompositeApiTracer(List<ApiTracer> tracers) {
+    this.tracers = ImmutableList.copyOf(tracers);
+  }
+
+  @Override
+  public Scope inScope() {
+    List<Scope> scopes = tracers.stream().map(ApiTracer::inScope).collect(Collectors.toList());
+    return () -> scopes.forEach(Scope::close);
+  }
+
+  @Override
+  public void operationSucceeded() {
+    tracers.forEach(ApiTracer::operationSucceeded);
+  }
+
+  @Override
+  public void operationCancelled() {
+    tracers.forEach(ApiTracer::operationCancelled);
+  }
+
+  @Override
+  public void operationFailed(Throwable error) {
+    tracers.forEach(t -> t.operationFailed(error));
+  }
+
+  @Override
+  public void connectionSelected(String id) {
+    tracers.forEach(t -> t.connectionSelected(id));
+  }
+
+  @Override
+  public void attemptStarted(int attemptNumber) {
+    tracers.forEach(t -> t.attemptStarted(attemptNumber));
+  }
+
+  @Override
+  public void attemptStarted(Object request, int attemptNumber) {
+    tracers.forEach(t -> t.attemptStarted(request, attemptNumber));
+  }
+
+  @Override
+  public void attemptSucceeded() {
+    tracers.forEach(ApiTracer::attemptSucceeded);
+  }
+
+  @Override
+  public void attemptCancelled() {
+    tracers.forEach(ApiTracer::attemptCancelled);
+  }
+
+  @Override
+  public void attemptFailedDuration(Throwable error, java.time.Duration delay) {
+    tracers.forEach(t -> t.attemptFailedDuration(error, delay));
+  }
+
+  @Override
+  public void attemptFailedRetriesExhausted(Throwable error) {
+    tracers.forEach(t -> t.attemptFailedRetriesExhausted(error));
+  }
+
+  @Override
+  public void attemptPermanentFailure(Throwable error) {
+    tracers.forEach(t -> t.attemptPermanentFailure(error));
+  }
+
+  @Override
+  public void lroStartFailed(Throwable error) {
+    tracers.forEach(t -> t.lroStartFailed(error));
+  }
+
+  @Override
+  public void lroStartSucceeded() {
+    tracers.forEach(ApiTracer::lroStartSucceeded);
+  }
+
+  @Override
+  public void responseReceived() {
+    tracers.forEach(ApiTracer::responseReceived);
+  }
+
+  @Override
+  public void requestSent() {
+    tracers.forEach(ApiTracer::requestSent);
+  }
+
+  @Override
+  public void batchRequestSent(long elementCount, long requestSize) {
+    tracers.forEach(t -> t.batchRequestSent(elementCount, requestSize));
+  }
+}

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

@@ -0,0 +1,61 @@
+/*
+ * 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.List;
+import java.util.stream.Collectors;
+
+/**
+ * A composite implementation of {@link ApiTracerFactory} that creates {@link CompositeApiTracer}s.
+ */
+@InternalApi
+public class CompositeApiTracerFactory implements ApiTracerFactory {
+  private final List<ApiTracerFactory> factories;
+
+  public CompositeApiTracerFactory(List<ApiTracerFactory> factories) {
+    this.factories = ImmutableList.copyOf(factories);
+  }
+
+  public static ApiTracerFactory of(ApiTracerFactory... factories) {
+    return new CompositeApiTracerFactory(ImmutableList.copyOf(factories));
+  }
+
+  @Override
+  public ApiTracer newTracer(ApiTracer parent, SpanName spanName, OperationType operationType) {
+    List<ApiTracer> tracers =
+        factories.stream()
+            .map(f -> f.newTracer(parent, spanName, operationType))
+            .collect(Collectors.toList());
+    return new CompositeApiTracer(tracers);
+  }
+}

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

@@ -0,0 +1,75 @@
+/*
+ * 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.BetaApi;
+import com.google.api.core.InternalApi;
+import com.google.api.gax.core.GaxProperties;
+import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.Tracer;
+import java.util.Map;
+
+/**
+ * OpenTelemetry implementation of recording traces. This implementation collects the measurements
+ * related to the lifecyle of an RPC.
+ */
+@BetaApi
+@InternalApi
+public class OpenTelemetryTracingRecorder implements TracingRecorder {
+  public static final String GAX_TRACER_NAME = "gax-java";
+  private final Tracer tracer;
+  private final String serviceName;
+
+  /**
+   * Creates a new instance of OpenTelemetryTracingRecorder.
+   *
+   * @param openTelemetry OpenTelemetry instance
+   * @param serviceName Service Name
+   */
+  public OpenTelemetryTracingRecorder(OpenTelemetry openTelemetry, String serviceName) {
+    this.tracer =
+        openTelemetry
+            .tracerBuilder(GAX_TRACER_NAME)
+            .setInstrumentationVersion(GaxProperties.getGaxVersion())
+            .build();
+    this.serviceName = serviceName;
+  }
+
+  @Override
+  public void recordLowLevelNetworkSpan(Map<String, String> attributes) {
+    Span span = tracer.spanBuilder(serviceName + "/low-level-network-span").startSpan();
+    if (attributes != null) {
+      attributes.forEach(span::setAttribute);
+    }
+    span.end();
+  }
+}

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

@@ -0,0 +1,54 @@
+/*
+ * 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.BetaApi;
+import com.google.api.core.InternalApi;
+import java.util.Map;
+
+/**
+ * Provides an interface for tracing recording. The implementer is expected to use an observability
+ * framework, e.g. OpenTelemetry. There should be only one instance of TracingRecorder per client,
+ * all the methods in this class are expected to be called from multiple threads, hence the
+ * implementation must be thread safe.
+ */
+@BetaApi
+@InternalApi
+public interface TracingRecorder {
+
+  /**
+   * Represents a low-level network span (T4) and serves as a placeholder for further development.
+   * This represents a single network request/attempt.
+   *
+   * @param attributes Map of the attributes to store on the span.
+   */
+  default void recordLowLevelNetworkSpan(Map<String, String> attributes) {}
+}