feat: log actionable errors on operation failure in LoggingTracer

Author: jinseopkim0

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

@@ -33,6 +33,8 @@
 import com.google.api.core.InternalApi;
 import java.util.Map;
 import org.jspecify.annotations.NullMarked;
+import org.slf4j.Logger;
+import org.slf4j.event.Level;
 
 @NullMarked
 @InternalApi
@@ -149,7 +151,7 @@ public static <RespT> void logRequest(
   }
 
   /**
-   * Logs an actionable error message with structured context at a specific log level.
+   * Logs an actionable error message with structured context at DEBUG level.
    *
    * @param logContext A map containing the structured logging context (e.g., RPC service, method,
    *     error details).
@@ -158,9 +160,23 @@ public static <RespT> void logRequest(
    */
   public static void logActionableError(
       Map<String, Object> logContext, LoggerProvider loggerProvider, String message) {
+    logActionableError(logContext, loggerProvider, message, Level.DEBUG);
+  }
+
+  /**
+   * Logs an actionable error message with structured context at a specified log level.
+   *
+   * @param logContext A map containing the structured logging context (e.g., RPC service, method,
+   *     error details).
+   * @param loggerProvider The provider used to obtain the logger.
+   * @param message The human-readable error message.
+   * @param level The SLF4J log level at which to emit the error log.
+   */
+  public static void logActionableError(
+      Map<String, Object> logContext, LoggerProvider loggerProvider, String message, Level level) {
     if (loggingEnabled) {
-      org.slf4j.Logger logger = loggerProvider.getLogger();
-      Slf4jUtils.log(logger, org.slf4j.event.Level.DEBUG, logContext, message);
+      Logger logger = loggerProvider.getLogger();
+      Slf4jUtils.log(logger, level, logContext, message);
     }
   }
 

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

@@ -38,6 +38,7 @@
 import java.util.HashMap;
 import java.util.Map;
 import org.jspecify.annotations.NullMarked;
+import org.slf4j.event.Level;
 
 /**
  * An {@link ApiTracer} that logs actionable errors using {@link LoggingUtils} when an RPC attempt
@@ -56,21 +57,47 @@ class LoggingTracer extends BaseApiTracer {
 
   @Override
   public void attemptFailedDuration(Throwable error, java.time.Duration delay) {
-    recordActionableError(error);
+    recordActionableError(error, Level.DEBUG);
   }
 
   @Override
   public void attemptFailedRetriesExhausted(Throwable error) {
-    recordActionableError(error);
+    recordActionableError(error, Level.DEBUG);
+  }
+
+  /**
+   * Records an actionable error log entry at ERROR level when the logical operation fails.
+   *
+   * @param error the exception that caused the logical operation to fail
+   */
+  @Override
+  public void operationFailed(Throwable error) {
+    recordActionableError(error, Level.ERROR);
   }
 
   @Override
   public void attemptPermanentFailure(Throwable error) {
-    recordActionableError(error);
+    recordActionableError(error, Level.DEBUG);
   }
 
+  /**
+   * Records an actionable error log entry at DEBUG level.
+   *
+   * @param error the exception that occurred
+   */
   @VisibleForTesting
   void recordActionableError(Throwable error) {
+    recordActionableError(error, Level.DEBUG);
+  }
+
+  /**
+   * Records an actionable error log entry with the specified log level.
+   *
+   * @param error the exception that occurred
+   * @param level the SLF4J log level at which to emit the error log
+   */
+  @VisibleForTesting
+  void recordActionableError(Throwable error, Level level) {
     if (error == null) {
       return;
     }
@@ -98,6 +125,6 @@ void recordActionableError(Throwable error) {
     }
 
     String message = error.getMessage() != null ? error.getMessage() : error.getClass().getName();
-    LoggingUtils.logActionableError(logContext, LOGGER_PROVIDER, message);
+    LoggingUtils.logActionableError(logContext, LOGGER_PROVIDER, message, level);
   }
 }

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

@@ -123,4 +123,24 @@ void testLogActionableError_success() {
 
     verify(loggerProvider).getLogger();
   }
+
+  @Test
+  void testLogActionableError_withLevel_success() {
+    LoggingUtils.setLoggingEnabled(true);
+    LoggerProvider loggerProvider =
+        mock(LoggerProvider.class, Mockito.withSettings().withoutAnnotations());
+    Logger logger = mock(Logger.class, Mockito.withSettings().withoutAnnotations());
+    when(loggerProvider.getLogger()).thenReturn(logger);
+
+    org.slf4j.spi.LoggingEventBuilder eventBuilder = mock(org.slf4j.spi.LoggingEventBuilder.class);
+    when(logger.atError()).thenReturn(eventBuilder);
+    when(eventBuilder.addKeyValue(anyString(), any())).thenReturn(eventBuilder);
+
+    Map<String, Object> context = Collections.singletonMap("key", "value");
+    LoggingUtils.logActionableError(
+        context, loggerProvider, "message", org.slf4j.event.Level.ERROR);
+
+    verify(loggerProvider).getLogger();
+    verify(logger).atError();
+  }
 }

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

@@ -52,6 +52,24 @@ public List<String> getMessageList() {
     return messageList;
   }
 
+  /**
+   * Returns the most recent log level recorded by this test logger.
+   *
+   * @return the SLF4J {@link Level} or null if no level has been recorded
+   */
+  public Level getLevel() {
+    return level;
+  }
+
+  /**
+   * Sets or clears the log level recorded by this test logger.
+   *
+   * @param level the SLF4J {@link Level} to set
+   */
+  public void setLevel(Level level) {
+    this.level = level;
+  }
+
   Map<String, Object> keyValuePairsMap = new HashMap<>();
 
   public Map<String, String> getMDCMap() {

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

@@ -44,6 +44,7 @@
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.slf4j.LoggerFactory;
+import org.slf4j.event.Level;
 
 class LoggingTracerTest {
 
@@ -55,6 +56,7 @@ void setUp() {
     testLogger.getMessageList().clear();
     testLogger.getMDCMap().clear();
     testLogger.getKeyValuePairsMap().clear();
+    testLogger.setLevel(null);
   }
 
   @Test
@@ -67,6 +69,7 @@ void testAttemptFailedDuration_LogsError() {
 
     assertEquals(1, testLogger.getMessageList().size());
     assertEquals("generic failure duration", testLogger.getMessageList().get(0));
+    assertEquals(Level.DEBUG, testLogger.getLevel());
   }
 
   @Test
@@ -79,6 +82,7 @@ void testAttemptFailedRetriesExhausted_LogsError() {
 
     assertEquals(1, testLogger.getMessageList().size());
     assertEquals("generic failure retries exhausted", testLogger.getMessageList().get(0));
+    assertEquals(Level.DEBUG, testLogger.getLevel());
   }
 
   @Test
@@ -91,6 +95,20 @@ void testAttemptPermanentFailure_LogsError() {
 
     assertEquals(1, testLogger.getMessageList().size());
     assertEquals("generic permanent failure", testLogger.getMessageList().get(0));
+    assertEquals(Level.DEBUG, testLogger.getLevel());
+  }
+
+  @Test
+  void testOperationFailed_LogsError() {
+    ApiTracerContext context = ApiTracerContext.empty();
+    LoggingTracer tracer = new LoggingTracer(context);
+
+    Exception error = new RuntimeException("generic operation failure");
+    tracer.operationFailed(error);
+
+    assertEquals(1, testLogger.getMessageList().size());
+    assertEquals("generic operation failure", testLogger.getMessageList().get(0));
+    assertEquals(Level.ERROR, testLogger.getLevel());
   }
 
   @Test
@@ -103,6 +121,7 @@ void testRecordActionableError_logsErrorMessage() {
 
     assertEquals(1, testLogger.getMessageList().size());
     assertEquals("test error message", testLogger.getMessageList().get(0));
+    assertEquals(Level.DEBUG, testLogger.getLevel());
   }
 
   @Test