Class ExceptionLog

java.lang.Object
cloud.opencode.base.log.enhance.ExceptionLog
public final class ExceptionLog extends Object
Exception Logging Enhancement - Smart Exception Logging 异常日志增强 - 智能异常日志

Provides enhanced exception logging capabilities including:

提供增强的异常日志能力，包括：

  • Root cause analysis - 根因分析
  • Exception chain formatting - 异常链格式化
  • Deduplication (same exception logged only once) - 去重（相同异常仅记录一次）
  • Rate limiting - 限速
  • Exception summarization - 异常摘要

Usage Example | 使用示例:

try {
    processOrder(order);
} catch (Exception e) {
    // Smart logging with root cause analysis
    ExceptionLog.error("Order processing failed: orderId=" + orderId, e);
    // Output:
    // ERROR Order processing failed: orderId=123
    // Root Cause: SQLException: Connection refused
    // Exception Chain: OrderProcessException -> ServiceException -> SQLException

    // Log once (avoid log flooding)
    ExceptionLog.errorOnce("Service unavailable", e);

    // Rate-limited logging
    ExceptionLog.errorRateLimited("DB connection failed", e, Duration.ofMinutes(1));
}

Features | 主要功能:

  • Root cause analysis and exception chain formatting - 根因分析和异常链格式化
  • Exception deduplication (log once per unique signature) - 异常去重（每个唯一签名仅记录一次）
  • Rate-limited exception logging - 限速异常日志
  • Compact stack trace with configurable depth - 可配置深度的紧凑堆栈跟踪

Security | 安全性:

  • Thread-safe: Yes (ConcurrentHashMap + AtomicLong) - 线程安全: 是（ConcurrentHashMap + AtomicLong）
  • Null-safe: Yes (handles null throwable) - 空值安全: 是（处理 null 异常）
Since:
JDK 25, opencode-base-log V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • error

      public static void error(String message, Throwable throwable)
      Logs an error with root cause analysis 带根因分析记录错误
      Parameters:
      message - the log message | 日志消息
      throwable - the exception | 异常

    • errorOnce

      public static void errorOnce(String message, Throwable throwable)
      Logs an error only once per unique exception signature 每个唯一异常签名仅记录一次错误

      Note: Tracks at most 10,000 unique signatures to prevent memory leaks. When the limit is reached, the tracking set is cleared and logging resumes.

      Parameters:
      message - the log message | 日志消息
      throwable - the exception | 异常

    • errorRateLimited

      public static void errorRateLimited(String message, Throwable throwable, Duration interval)
      Logs an error with rate limiting 带限速记录错误
      Parameters:
      message - the log message | 日志消息
      throwable - the exception | 异常
      interval - minimum interval between logs | 日志之间的最小间隔

    • warn

      public static void warn(String message, Throwable throwable)
      Logs a warning with root cause analysis 带根因分析记录警告
      Parameters:
      message - the log message | 日志消息
      throwable - the exception | 异常

    • getRootCause

      public static Throwable getRootCause(Throwable throwable)
      Gets the root cause of an exception 获取异常的根因
      Parameters:
      throwable - the exception | 异常
      Returns:
      the root cause | 根因

    • getCausalChain

      public static List<Throwable> getCausalChain(Throwable throwable)
      Gets the causal chain of an exception 获取异常的因果链
      Parameters:
      throwable - the exception | 异常
      Returns:
      list of exceptions in the chain | 链中的异常列表

    • formatExceptionChain

      public static String formatExceptionChain(Throwable throwable)
      Formats the exception chain as a string 将异常链格式化为字符串
      Parameters:
      throwable - the exception | 异常
      Returns:
      formatted chain string | 格式化的链字符串

    • summarize

      public static String summarize(Throwable throwable)
      Creates a summary of an exception 创建异常摘要
      Parameters:
      throwable - the exception | 异常
      Returns:
      summary string | 摘要字符串

    • getStackTraceString

      public static String getStackTraceString(Throwable throwable)
      Gets the stack trace as a string 获取堆栈跟踪字符串
      Parameters:
      throwable - the exception | 异常
      Returns:
      stack trace string | 堆栈跟踪字符串

    • getCompactStackTrace

      public static String getCompactStackTrace(Throwable throwable, int maxDepth)
      Gets a compact stack trace (limited depth) 获取紧凑的堆栈跟踪（有限深度）
      Parameters:
      throwable - the exception | 异常
      maxDepth - maximum stack trace depth | 最大堆栈跟踪深度
      Returns:
      compact stack trace | 紧凑的堆栈跟踪

    • getExceptionSignature

      public static String getExceptionSignature(Throwable throwable)
      Gets a unique signature for an exception (for deduplication) 获取异常的唯一签名（用于去重）
      Parameters:
      throwable - the exception | 异常
      Returns:
      signature string | 签名字符串

    • containsExceptionType

      public static boolean containsExceptionType(Throwable throwable, Class<? extends Throwable> targetType)
      Checks if an exception contains a specific exception type in its chain 检查异常链中是否包含特定异常类型
      Parameters:
      throwable - the exception | 异常
      targetType - the type to check for | 要检查的类型
      Returns:
      true if found | 如果找到返回 true

    • findExceptionOfType

      public static <T extends Throwable> T findExceptionOfType(Throwable throwable, Class<T> targetType)
      Finds an exception of specific type in the causal chain 在因果链中查找特定类型的异常
      Type Parameters:
      T - the exception type | 异常类型
      Parameters:
      throwable - the exception | 异常
      targetType - the type to find | 要查找的类型
      Returns:
      the found exception or null | 找到的异常或 null

    • clearDeduplicationTracking

      public static void clearDeduplicationTracking()
      Clears the deduplication tracking (useful for testing) 清除去重追踪（用于测试）

    • clearRateLimitTracking

      public static void clearRateLimitTracking()
      Clears the rate limit tracking (useful for testing) 清除限速追踪（用于测试）