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,19 @@
 @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() {
+  public static boolean isLoggingEnabled() {
+    return loggingEnabled;
+  }
+
+  // visible for testing
+  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 +135,24 @@ public static <RespT> void logRequest(
     }
   }
 
+  /**
+   * Logs an actionable error message with structured context.
+   *
+   * @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.
+   */
+  public static void logActionableError(
+      Map<String, Object> logContext, LoggerProvider loggerProvider, String message) {
+    if (loggingEnabled) {
+      org.slf4j.Logger logger = loggerProvider.getLogger();
+      if (logger.isInfoEnabled()) {
+        Slf4jUtils.log(logger, org.slf4j.event.Level.INFO, logContext, message);
+      }
+    }
+  }
+
   public static void executeWithTryCatch(ThrowingRunnable action) {
     try {
       action.run();