feat(gax): add utilities for logging actionable errors

Author: westarle

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

@@ -36,10 +36,28 @@
 @InternalApi
 public class LoggingUtils {
 
-  private static boolean loggingEnabled = isLoggingEnabled();
+  private static boolean loggingEnabled = checkLoggingEnabled();
   static final String GOOGLE_SDK_JAVA_LOGGING = "GOOGLE_SDK_JAVA_LOGGING";
 
-  static boolean isLoggingEnabled() {
+  /**
+   * Returns whether client-side logging is enabled.
+   *
+   * @return true if logging is enabled, false otherwise.
+   */
+  public static boolean isLoggingEnabled() {
+    return loggingEnabled;
+  }
+
+  /**
+   * Sets whether client-side logging is enabled. Visible for testing.
+   *
+   * @param enabled true to enable logging, false to disable.
+   */
+  public static void setLoggingEnabled(boolean enabled) {
+    loggingEnabled = enabled;
+  }
+
+  private static boolean checkLoggingEnabled() {
     String enableLogging = System.getenv(GOOGLE_SDK_JAVA_LOGGING);
     return "true".equalsIgnoreCase(enableLogging);
   }
@@ -126,6 +144,26 @@ public static <RespT> void logRequest(
     }
   }
 
+  /**
+   * Logs an actionable error message with structured context at a specific 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 level The slf4j level to log the actionable error at.
+   * @param message The human-readable error message.
+   */
+  public static void logActionableError(
+      Map<String, Object> logContext,
+      LoggerProvider loggerProvider,
+      org.slf4j.event.Level level,
+      String message) {
+    if (loggingEnabled) {
+      org.slf4j.Logger logger = loggerProvider.getLogger();
+      Slf4jUtils.log(logger, level, logContext, message);
+    }
+  }
+
   public static void executeWithTryCatch(ThrowingRunnable action) {
     try {
       action.run();

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

@@ -33,11 +33,20 @@
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
 import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
 
 import com.google.api.gax.logging.LoggingUtils.ThrowingRunnable;
+import java.util.Collections;
+import java.util.Map;
+import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.Test;
 import org.mockito.Mockito;
+import org.slf4j.Logger;
 
 class LoggingUtilsTest {
 
@@ -77,4 +86,37 @@ void testExecuteWithTryCatch_WithNoSuchMethodError() throws Throwable {
     // Verify that the action was executed (despite the error)
     verify(action).run();
   }
+
+  @AfterEach
+  void tearDown() {
+    LoggingUtils.setLoggingEnabled(false);
+  }
+
+  @Test
+  void testLogActionableError_loggingDisabled() {
+    LoggingUtils.setLoggingEnabled(false);
+    LoggerProvider loggerProvider = mock(LoggerProvider.class);
+
+    LoggingUtils.logActionableError(
+        Collections.emptyMap(), loggerProvider, org.slf4j.event.Level.INFO, "message");
+
+    verify(loggerProvider, never()).getLogger();
+  }
+
+  @Test
+  void testLogActionableError_success() {
+    LoggingUtils.setLoggingEnabled(true);
+    LoggerProvider loggerProvider = mock(LoggerProvider.class);
+    Logger logger = mock(Logger.class);
+    when(loggerProvider.getLogger()).thenReturn(logger);
+
+    org.slf4j.spi.LoggingEventBuilder eventBuilder = mock(org.slf4j.spi.LoggingEventBuilder.class);
+    when(logger.atInfo()).thenReturn(eventBuilder);
+    when(eventBuilder.addKeyValue(anyString(), any())).thenReturn(eventBuilder);
+
+    Map<String, Object> context = Collections.singletonMap("key", "value");
+    LoggingUtils.logActionableError(context, loggerProvider, org.slf4j.event.Level.INFO, "message");
+
+    verify(loggerProvider).getLogger();
+  }
 }