feat(gax): Actionable Errors Logging API Tracer

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</test>
+          <test>!EndpointContextTest#endpointContextBuild_universeDomainEnvVarSet+endpointContextBuild_multipleUniverseDomainConfigurations_clientSettingsHasPriority,!LoggingEnabledTest,!LoggingTracerTest</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</test>
+              <test>EndpointContextTest#endpointContextBuild_universeDomainEnvVarSet+endpointContextBuild_multipleUniverseDomainConfigurations_clientSettingsHasPriority,LoggingEnabledTest,LoggingTracerTest</test>
             </configuration>
           </plugin>
         </plugins>

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

@@ -0,0 +1,108 @@
+/*
+ * 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.logging.LoggerProvider;
+import com.google.api.gax.logging.LoggingUtils;
+import com.google.rpc.ErrorInfo;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * An {@link ApiTracer} that logs actionable errors using {@link LoggingUtils} when an RPC attempt
+ * fails.
+ */
+@BetaApi
+@InternalApi
+public class LoggingTracer extends BaseApiTracer {
+  private static final LoggerProvider LOGGER_PROVIDER =
+      LoggerProvider.forClazz(LoggingTracer.class);
+
+  private final ApiTracerContext apiTracerContext;
+
+  public LoggingTracer(ApiTracerContext apiTracerContext) {
+    this.apiTracerContext = apiTracerContext;
+  }
+
+  @Override
+  public void attemptFailedDuration(Throwable error, java.time.Duration delay) {
+    recordActionableError(error);
+  }
+
+  @Override
+  public void attemptFailedRetriesExhausted(Throwable error) {
+    recordActionableError(error);
+  }
+
+  @Override
+  public void attemptPermanentFailure(Throwable error) {
+    recordActionableError(error);
+  }
+
+  private void recordActionableError(Throwable error) {
+    if (error == null) {
+      return;
+    }
+
+    Map<String, Object> logContext = new HashMap<>(apiTracerContext.getAttemptAttributes());
+
+    if (apiTracerContext.serviceName() != null) {
+      logContext.put(
+          ObservabilityAttributes.GCP_CLIENT_SERVICE_ATTRIBUTE, apiTracerContext.serviceName());
+    }
+
+    logContext.put(
+        ObservabilityAttributes.RPC_RESPONSE_STATUS_ATTRIBUTE,
+        ObservabilityUtils.extractStatus(error));
+
+    ErrorInfo errorInfo = ObservabilityUtils.extractErrorInfo(error);
+    if (errorInfo != null) {
+      if (errorInfo.getReason() != null && !errorInfo.getReason().isEmpty()) {
+        logContext.put(ObservabilityAttributes.ERROR_TYPE_ATTRIBUTE, errorInfo.getReason());
+      }
+      if (errorInfo.getDomain() != null && !errorInfo.getDomain().isEmpty()) {
+        logContext.put(ObservabilityAttributes.ERROR_DOMAIN_ATTRIBUTE, errorInfo.getDomain());
+      }
+      if (errorInfo.getMetadataMap() != null) {
+        for (Map.Entry<String, String> entry : errorInfo.getMetadataMap().entrySet()) {
+          logContext.put(
+              ObservabilityAttributes.ERROR_METADATA_ATTRIBUTE_PREFIX + entry.getKey(),
+              entry.getValue());
+        }
+      }
+    }
+
+    String message = error.getMessage() != null ? error.getMessage() : error.getClass().getName();
+    LoggingUtils.logActionableError(logContext, LOGGER_PROVIDER, message);
+  }
+}

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

@@ -0,0 +1,69 @@
+/*
+ * 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;
+
+/** A {@link ApiTracerFactory} that creates instances of {@link LoggingTracer}. */
+@BetaApi
+@InternalApi
+public class LoggingTracerFactory implements ApiTracerFactory {
+  private final ApiTracerContext apiTracerContext;
+
+  public LoggingTracerFactory() {
+    this(ApiTracerContext.empty());
+  }
+
+  private LoggingTracerFactory(ApiTracerContext apiTracerContext) {
+    this.apiTracerContext = apiTracerContext;
+  }
+
+  @Override
+  public ApiTracer newTracer(ApiTracer parent, SpanName spanName, OperationType operationType) {
+    return new LoggingTracer(apiTracerContext);
+  }
+
+  @Override
+  public ApiTracer newTracer(ApiTracer parent, ApiTracerContext context) {
+    return new LoggingTracer(apiTracerContext.merge(context));
+  }
+
+  @Override
+  public ApiTracerContext getApiTracerContext() {
+    return apiTracerContext;
+  }
+
+  @Override
+  public ApiTracerFactory withContext(ApiTracerContext context) {
+    return new LoggingTracerFactory(apiTracerContext.merge(context));
+  }
+}

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

@@ -96,4 +96,13 @@ public class ObservabilityAttributes {
 
   /** The destination resource id of the request (e.g. projects/p/locations/l/topics/t). */
   public static final String DESTINATION_RESOURCE_ID_ATTRIBUTE = "gcp.resource.destination.id";
+
+  /** The type of error that occurred (e.g., from google.rpc.ErrorInfo.reason). */
+  public static final String ERROR_TYPE_ATTRIBUTE = "error.type";
+
+  /** The domain of the error (e.g., from google.rpc.ErrorInfo.domain). */
+  public static final String ERROR_DOMAIN_ATTRIBUTE = "gcp.errors.domain";
+
+  /** The prefix for error metadata (e.g., from google.rpc.ErrorInfo.metadata). */
+  public static final String ERROR_METADATA_ATTRIBUTE_PREFIX = "gcp.errors.metadata.";
 }

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

@@ -31,6 +31,7 @@
 
 import com.google.api.gax.rpc.ApiException;
 import com.google.api.gax.rpc.StatusCode;
+import com.google.rpc.ErrorInfo;
 import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.common.AttributesBuilder;
 import java.util.Map;
@@ -56,6 +57,18 @@ static String extractStatus(@Nullable Throwable error) {
     return statusString;
   }
 
+  /** Function to extract the ErrorInfo payload from the error, if available */
+  @Nullable
+  static ErrorInfo extractErrorInfo(@Nullable Throwable error) {
+    if (error instanceof ApiException) {
+      ApiException apiException = (ApiException) error;
+      if (apiException.getErrorDetails() != null) {
+        return apiException.getErrorDetails().getErrorInfo();
+      }
+    }
+    return null;
+  }
+
   static Attributes toOtelAttributes(Map<String, Object> attributes) {
     AttributesBuilder attributesBuilder = Attributes.builder();
     if (attributes == null) {

sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/logging/TestLogger.java

@@ -48,8 +48,20 @@ public class TestLogger implements Logger, LoggingEventAware {
   List<String> messageList = new ArrayList<>();
   Level level;
 
+  public List<String> getMessageList() {
+    return messageList;
+  }
+
   Map<String, Object> keyValuePairsMap = new HashMap<>();
 
+  public Map<String, String> getMDCMap() {
+    return MDCMap;
+  }
+
+  public Map<String, Object> getKeyValuePairsMap() {
+    return keyValuePairsMap;
+  }
+
   private String loggerName;
   private boolean infoEnabled;
   private boolean debugEnabled;

sdk-platform-java/gax-java/gax/src/test/java/com/google/api/gax/logging/TestServiceProvider.java

@@ -30,12 +30,11 @@
 
 package com.google.api.gax.logging;
 
-import static org.mockito.ArgumentMatchers.anyString;
-import static org.mockito.Mockito.mock;
-import static org.mockito.Mockito.when;
-
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
 import org.slf4j.ILoggerFactory;
 import org.slf4j.IMarkerFactory;
+import org.slf4j.Logger;
 import org.slf4j.spi.MDCAdapter;
 import org.slf4j.spi.SLF4JServiceProvider;
 
@@ -45,12 +44,18 @@
  */
 public class TestServiceProvider implements SLF4JServiceProvider {
 
+  private final ConcurrentMap<String, Logger> loggers = new ConcurrentHashMap<>();
+  private final ILoggerFactory loggerFactory =
+      new ILoggerFactory() {
+        @Override
+        public Logger getLogger(String name) {
+          return loggers.computeIfAbsent(name, TestLogger::new);
+        }
+      };
+
   @Override
   public ILoggerFactory getLoggerFactory() {
-    // mock behavior when provider present
-    ILoggerFactory mockLoggerFactory = mock(ILoggerFactory.class);
-    when(mockLoggerFactory.getLogger(anyString())).thenReturn(new TestLogger("test-logger"));
-    return mockLoggerFactory;
+    return loggerFactory;
   }
 
   @Override

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

@@ -0,0 +1,74 @@
+/*
+ * 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 static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+
+class LoggingTracerFactoryTest {
+
+  @Test
+  void testNewTracer_CreatesLoggingTracer() {
+    LoggingTracerFactory factory = new LoggingTracerFactory();
+    ApiTracer tracer =
+        factory.newTracer(
+            BaseApiTracer.getInstance(),
+            SpanName.of("client", "method"),
+            ApiTracerFactory.OperationType.Unary);
+
+    assertNotNull(tracer);
+    assertTrue(tracer instanceof LoggingTracer);
+  }
+
+  @Test
+  void testNewTracer_WithContext_CreatesLoggingTracer() {
+    LoggingTracerFactory factory = new LoggingTracerFactory();
+    ApiTracer tracer = factory.newTracer(BaseApiTracer.getInstance(), ApiTracerContext.empty());
+
+    assertNotNull(tracer);
+    assertTrue(tracer instanceof LoggingTracer);
+  }
+
+  @Test
+  void testWithContext_ReturnsNewFactoryWithMergedContext() {
+    LoggingTracerFactory factory = new LoggingTracerFactory();
+    ApiTracerContext context =
+        ApiTracerContext.empty().toBuilder().setServerAddress("address").build();
+    ApiTracerFactory updatedFactory = factory.withContext(context);
+
+    assertNotNull(updatedFactory);
+    assertTrue(updatedFactory instanceof LoggingTracerFactory);
+    assertEquals("address", updatedFactory.getApiTracerContext().serverAddress());
+  }
+}