cloud.opencode.base.log.async.AsyncLogger

All Implemented Interfaces:: Logger, AutoCloseable

public final class AsyncLogger extends Object implements Logger, AutoCloseable

Asynchronous Logger - Offloads log output to a virtual thread via a bounded queue 异步日志记录器 - 通过有界队列将日志输出卸载到虚拟线程

AsyncLogger wraps a delegate Logger and dispatches log messages asynchronously using a single daemon virtual thread that consumes from a bounded blocking queue. When the queue is full, logging falls back to synchronous execution on the caller thread to ensure no messages are dropped or blocked.

AsyncLogger 包装一个委托 Logger，使用单个守护虚拟线程从有界阻塞队列中消费，异步分发日志消息。当队列满时，日志回退到调用者线程上同步执行，确保消息不会丢失或阻塞。

Features | 主要功能:

Asynchronous log dispatch via virtual thread - 通过虚拟线程异步分发日志
Bounded queue with configurable capacity - 可配置容量的有界队列
Backpressure: synchronous fallback when queue is full - 背压：队列满时同步回退
MDC context propagation across threads - MDC 上下文跨线程传播
Flush and graceful shutdown support - 刷新和优雅关闭支持

Usage Examples | 使用示例:

Logger delegate = LoggerFactory.getLogger(MyService.class);
try (AsyncLogger asyncLogger = AsyncLogger.wrap(delegate)) {
    asyncLogger.info("This is logged asynchronously");
    asyncLogger.flush(); // Wait for all pending messages to be processed
}

// Custom queue capacity
AsyncLogger asyncLogger = AsyncLogger.wrap(delegate, 4096);

Security | 安全性:

Thread-safe: Yes - 线程安全: 是
Null-safe: No (delegate must not be null) - 空值安全: 否（委托不能为 null）

Since:

JDK 25, opencode-base-log V1.0.3

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

void

close()

Closes this async logger, equivalent to shutdown().

void

debug(Marker marker, String message)

Logs a message at DEBUG level with a marker.

void

debug(Marker marker, String format, Object... args)

Logs a message at DEBUG level with a marker and parameters.

void

debug(String message)

Logs a message at DEBUG level.

void

debug(String format, Object... args)

Logs a message at DEBUG level with parameters.

void

debug(String message, Throwable throwable)

Logs a message at DEBUG level with an exception.

void

debug(Supplier<String> messageSupplier)

Logs a message at DEBUG level using lazy evaluation.

void

error(Marker marker, String message)

Logs a message at ERROR level with a marker.

void

error(Marker marker, String format, Object... args)

Logs a message at ERROR level with a marker and parameters.

void

error(Marker marker, String message, Throwable throwable)

Logs a message at ERROR level with a marker and exception.

void

error(String message)

Logs a message at ERROR level.

void

error(String format, Object... args)

Logs a message at ERROR level with parameters.

void

error(String message, Throwable throwable)

Logs a message at ERROR level with an exception.

void

error(Throwable throwable)

Logs an exception at ERROR level.

void

error(Supplier<String> messageSupplier)

Logs a message at ERROR level using lazy evaluation.

void

error(Supplier<String> messageSupplier, Throwable throwable)

Logs a message at ERROR level using lazy evaluation with exception.

void

flush()

Blocks until all currently queued log tasks have been processed, or timeout expires.

String

getName()

Returns the name of this logger.

void

info(Marker marker, String message)

Logs a message at INFO level with a marker.

void

info(Marker marker, String format, Object... args)

Logs a message at INFO level with a marker and parameters.

void

info(String message)

Logs a message at INFO level.

void

info(String format, Object... args)

Logs a message at INFO level with parameters.

void

info(String message, Throwable throwable)

Logs a message at INFO level with an exception.

void

info(Supplier<String> messageSupplier)

Logs a message at INFO level using lazy evaluation.

boolean

isDebugEnabled()

Checks if DEBUG level is enabled.

boolean

isDebugEnabled(Marker marker)

Checks if DEBUG level is enabled for the specified marker.

boolean

isEnabled(LogLevel level)

Checks if the specified level is enabled.

boolean

isErrorEnabled()

Checks if ERROR level is enabled.

boolean

isErrorEnabled(Marker marker)

Checks if ERROR level is enabled for the specified marker.

boolean

isInfoEnabled()

Checks if INFO level is enabled.

boolean

isInfoEnabled(Marker marker)

Checks if INFO level is enabled for the specified marker.

boolean

isTraceEnabled()

Checks if TRACE level is enabled.

boolean

isTraceEnabled(Marker marker)

Checks if TRACE level is enabled for the specified marker.

boolean

isWarnEnabled()

Checks if WARN level is enabled.

boolean

isWarnEnabled(Marker marker)

Checks if WARN level is enabled for the specified marker.

void

log(LogLevel level, String message)

Logs a message at the specified level.

void

log(LogLevel level, String format, Object... args)

Logs a message at the specified level with parameters.

void

log(LogLevel level, String message, Throwable throwable)

Logs a message at the specified level with an exception.

void

shutdown()

Initiates graceful shutdown.

void

trace(Marker marker, String message)

Logs a message at TRACE level with a marker.

void

trace(Marker marker, String format, Object... args)

Logs a message at TRACE level with a marker and parameters.

void

trace(String message)

Logs a message at TRACE level.

void

trace(String format, Object... args)

Logs a message at TRACE level with parameters.

void

trace(String message, Throwable throwable)

Logs a message at TRACE level with an exception.

void

trace(Supplier<String> messageSupplier)

Logs a message at TRACE level using lazy evaluation.

void

warn(Marker marker, String message)

Logs a message at WARN level with a marker.

void

warn(Marker marker, String format, Object... args)

Logs a message at WARN level with a marker and parameters.

void

warn(Marker marker, String message, Throwable throwable)

Logs a message at WARN level with a marker and exception.

void

warn(String message)

Logs a message at WARN level.

void

warn(String format, Object... args)

Logs a message at WARN level with parameters.

void

warn(String message, Throwable throwable)

Logs a message at WARN level with an exception.

void

warn(Supplier<String> messageSupplier)

Logs a message at WARN level using lazy evaluation.

static AsyncLogger

wrap(Logger delegate)

Wraps the given logger with async dispatch using the default queue capacity (8192).

static AsyncLogger

wrap(Logger delegate, int queueCapacity)

Wraps the given logger with async dispatch using the specified queue capacity.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- wrap
  
  public static AsyncLogger wrap(Logger delegate)
  
  Wraps the given logger with async dispatch using the default queue capacity (8192). 使用默认队列容量（8192）将给定日志记录器包装为异步分发。
  
  Parameters:
  
  delegate - the delegate logger - 委托日志记录器
  
  Returns:
  
  a new AsyncLogger instance - 新的 AsyncLogger 实例
  
  Throws:
  
  NullPointerException - if delegate is null - 如果委托为 null
- wrap
  
  public static AsyncLogger wrap(Logger delegate, int queueCapacity)
  
  Wraps the given logger with async dispatch using the specified queue capacity. 使用指定队列容量将给定日志记录器包装为异步分发。
  
  Parameters:
  
  delegate - the delegate logger - 委托日志记录器
  
  queueCapacity - the queue capacity - 队列容量
  
  Returns:
  
  a new AsyncLogger instance - 新的 AsyncLogger 实例
  
  Throws:
  
  NullPointerException - if delegate is null - 如果委托为 null
  
  IllegalArgumentException - if queueCapacity is not positive - 如果队列容量不为正数
- flush
  
  public void flush() throws InterruptedException
  
  Blocks until all currently queued log tasks have been processed, or timeout expires. 阻塞直到所有当前排队的日志任务被处理，或超时到期。
  
  Throws:
  
  InterruptedException - if the current thread is interrupted while waiting 如果当前线程在等待时被中断
- shutdown
  
  public void shutdown()
  
  Initiates graceful shutdown. Waits up to 5 seconds for queue drain, then interrupts. 启动优雅关闭。等待最多 5 秒让队列清空，然后中断。
- close
  
  public void close()
  
  Closes this async logger, equivalent to shutdown(). 关闭此异步日志记录器，等同于 shutdown()。
  
  Specified by:
  
  close in interface AutoCloseable
- getName
  
  public String getName()
  
  Returns the name of this logger. 返回此日志记录器的名称。
  
  Specified by:
  
  getName in interface Logger
  
  Returns:
  
  the logger name - 日志记录器名称
- isTraceEnabled
  
  public boolean isTraceEnabled()
  
  Checks if TRACE level is enabled. 检查 TRACE 级别是否启用。
  
  Specified by:
  
  isTraceEnabled in interface Logger
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isTraceEnabled
  
  public boolean isTraceEnabled(Marker marker)
  
  Checks if TRACE level is enabled for the specified marker. 检查指定标记的 TRACE 级别是否启用。
  
  Specified by:
  
  isTraceEnabled in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isDebugEnabled
  
  public boolean isDebugEnabled()
  
  Checks if DEBUG level is enabled. 检查 DEBUG 级别是否启用。
  
  Specified by:
  
  isDebugEnabled in interface Logger
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isDebugEnabled
  
  public boolean isDebugEnabled(Marker marker)
  
  Checks if DEBUG level is enabled for the specified marker. 检查指定标记的 DEBUG 级别是否启用。
  
  Specified by:
  
  isDebugEnabled in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isInfoEnabled
  
  public boolean isInfoEnabled()
  
  Checks if INFO level is enabled. 检查 INFO 级别是否启用。
  
  Specified by:
  
  isInfoEnabled in interface Logger
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isInfoEnabled
  
  public boolean isInfoEnabled(Marker marker)
  
  Checks if INFO level is enabled for the specified marker. 检查指定标记的 INFO 级别是否启用。
  
  Specified by:
  
  isInfoEnabled in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isWarnEnabled
  
  public boolean isWarnEnabled()
  
  Checks if WARN level is enabled. 检查 WARN 级别是否启用。
  
  Specified by:
  
  isWarnEnabled in interface Logger
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isWarnEnabled
  
  public boolean isWarnEnabled(Marker marker)
  
  Checks if WARN level is enabled for the specified marker. 检查指定标记的 WARN 级别是否启用。
  
  Specified by:
  
  isWarnEnabled in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isErrorEnabled
  
  public boolean isErrorEnabled()
  
  Checks if ERROR level is enabled. 检查 ERROR 级别是否启用。
  
  Specified by:
  
  isErrorEnabled in interface Logger
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isErrorEnabled
  
  public boolean isErrorEnabled(Marker marker)
  
  Checks if ERROR level is enabled for the specified marker. 检查指定标记的 ERROR 级别是否启用。
  
  Specified by:
  
  isErrorEnabled in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  Returns:
  
  true if enabled - 如果启用返回 true
- isEnabled
  
  public boolean isEnabled(LogLevel level)
  
  Checks if the specified level is enabled. 检查指定级别是否启用。
  
  Specified by:
  
  isEnabled in interface Logger
  
  Parameters:
  
  level - the log level - 日志级别
  
  Returns:
  
  true if enabled - 如果启用返回 true
- trace
  
  public void trace(String message)
  
  Logs a message at TRACE level. 在 TRACE 级别记录消息。
  
  Specified by:
  
  trace in interface Logger
  
  Parameters:
  
  message - the message - 消息
- trace
  
  public void trace(String format, Object... args)
  
  Logs a message at TRACE level with parameters. 在 TRACE 级别记录带参数的消息。
  
  Specified by:
  
  trace in interface Logger
  
  Parameters:
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- trace
  
  public void trace(String message, Throwable throwable)
  
  Logs a message at TRACE level with an exception. 在 TRACE 级别记录带异常的消息。
  
  Specified by:
  
  trace in interface Logger
  
  Parameters:
  
  message - the message - 消息
  
  throwable - the exception - 异常
- trace
  
  public void trace(Supplier<String> messageSupplier)
  
  Logs a message at TRACE level using lazy evaluation. 使用延迟求值在 TRACE 级别记录消息。
  
  Specified by:
  
  trace in interface Logger
  
  Parameters:
  
  messageSupplier - the message supplier - 消息提供者
- trace
  
  public void trace(Marker marker, String message)
  
  Logs a message at TRACE level with a marker. 使用标记在 TRACE 级别记录消息。
  
  Specified by:
  
  trace in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  message - the message - 消息
- trace
  
  public void trace(Marker marker, String format, Object... args)
  
  Logs a message at TRACE level with a marker and parameters. 使用标记和参数在 TRACE 级别记录消息。
  
  Specified by:
  
  trace in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- debug
  
  public void debug(String message)
  
  Logs a message at DEBUG level. 在 DEBUG 级别记录消息。
  
  Specified by:
  
  debug in interface Logger
  
  Parameters:
  
  message - the message - 消息
- debug
  
  public void debug(String format, Object... args)
  
  Logs a message at DEBUG level with parameters. 在 DEBUG 级别记录带参数的消息。
  
  Specified by:
  
  debug in interface Logger
  
  Parameters:
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- debug
  
  public void debug(String message, Throwable throwable)
  
  Logs a message at DEBUG level with an exception. 在 DEBUG 级别记录带异常的消息。
  
  Specified by:
  
  debug in interface Logger
  
  Parameters:
  
  message - the message - 消息
  
  throwable - the exception - 异常
- debug
  
  public void debug(Supplier<String> messageSupplier)
  
  Logs a message at DEBUG level using lazy evaluation. 使用延迟求值在 DEBUG 级别记录消息。
  
  Specified by:
  
  debug in interface Logger
  
  Parameters:
  
  messageSupplier - the message supplier - 消息提供者
- debug
  
  public void debug(Marker marker, String message)
  
  Logs a message at DEBUG level with a marker. 使用标记在 DEBUG 级别记录消息。
  
  Specified by:
  
  debug in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  message - the message - 消息
- debug
  
  public void debug(Marker marker, String format, Object... args)
  
  Logs a message at DEBUG level with a marker and parameters. 使用标记和参数在 DEBUG 级别记录消息。
  
  Specified by:
  
  debug in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- info
  
  public void info(String message)
  
  Logs a message at INFO level. 在 INFO 级别记录消息。
  
  Specified by:
  
  info in interface Logger
  
  Parameters:
  
  message - the message - 消息
- info
  
  public void info(String format, Object... args)
  
  Logs a message at INFO level with parameters. 在 INFO 级别记录带参数的消息。
  
  Specified by:
  
  info in interface Logger
  
  Parameters:
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- info
  
  public void info(String message, Throwable throwable)
  
  Logs a message at INFO level with an exception. 在 INFO 级别记录带异常的消息。
  
  Specified by:
  
  info in interface Logger
  
  Parameters:
  
  message - the message - 消息
  
  throwable - the exception - 异常
- info
  
  public void info(Supplier<String> messageSupplier)
  
  Logs a message at INFO level using lazy evaluation. 使用延迟求值在 INFO 级别记录消息。
  
  Specified by:
  
  info in interface Logger
  
  Parameters:
  
  messageSupplier - the message supplier - 消息提供者
- info
  
  public void info(Marker marker, String message)
  
  Logs a message at INFO level with a marker. 使用标记在 INFO 级别记录消息。
  
  Specified by:
  
  info in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  message - the message - 消息
- info
  
  public void info(Marker marker, String format, Object... args)
  
  Logs a message at INFO level with a marker and parameters. 使用标记和参数在 INFO 级别记录消息。
  
  Specified by:
  
  info in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- warn
  
  public void warn(String message)
  
  Logs a message at WARN level. 在 WARN 级别记录消息。
  
  Specified by:
  
  warn in interface Logger
  
  Parameters:
  
  message - the message - 消息
- warn
  
  public void warn(String format, Object... args)
  
  Logs a message at WARN level with parameters. 在 WARN 级别记录带参数的消息。
  
  Specified by:
  
  warn in interface Logger
  
  Parameters:
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- warn
  
  public void warn(String message, Throwable throwable)
  
  Logs a message at WARN level with an exception. 在 WARN 级别记录带异常的消息。
  
  Specified by:
  
  warn in interface Logger
  
  Parameters:
  
  message - the message - 消息
  
  throwable - the exception - 异常
- warn
  
  public void warn(Supplier<String> messageSupplier)
  
  Logs a message at WARN level using lazy evaluation. 使用延迟求值在 WARN 级别记录消息。
  
  Specified by:
  
  warn in interface Logger
  
  Parameters:
  
  messageSupplier - the message supplier - 消息提供者
- warn
  
  public void warn(Marker marker, String message)
  
  Logs a message at WARN level with a marker. 使用标记在 WARN 级别记录消息。
  
  Specified by:
  
  warn in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  message - the message - 消息
- warn
  
  public void warn(Marker marker, String format, Object... args)
  
  Logs a message at WARN level with a marker and parameters. 使用标记和参数在 WARN 级别记录消息。
  
  Specified by:
  
  warn in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- warn
  
  public void warn(Marker marker, String message, Throwable throwable)
  
  Logs a message at WARN level with a marker and exception. 使用标记和异常在 WARN 级别记录消息。
  
  Specified by:
  
  warn in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  message - the message - 消息
  
  throwable - the exception - 异常
- error
  
  public void error(String message)
  
  Logs a message at ERROR level. 在 ERROR 级别记录消息。
  
  Specified by:
  
  error in interface Logger
  
  Parameters:
  
  message - the message - 消息
- error
  
  public void error(String format, Object... args)
  
  Logs a message at ERROR level with parameters. 在 ERROR 级别记录带参数的消息。
  
  Specified by:
  
  error in interface Logger
  
  Parameters:
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- error
  
  public void error(String message, Throwable throwable)
  
  Logs a message at ERROR level with an exception. 在 ERROR 级别记录带异常的消息。
  
  Specified by:
  
  error in interface Logger
  
  Parameters:
  
  message - the message - 消息
  
  throwable - the exception - 异常
- error
  
  public void error(Throwable throwable)
  
  Logs an exception at ERROR level. 在 ERROR 级别记录异常。
  
  Specified by:
  
  error in interface Logger
  
  Parameters:
  
  throwable - the exception - 异常
- error
  
  public void error(Supplier<String> messageSupplier)
  
  Logs a message at ERROR level using lazy evaluation. 使用延迟求值在 ERROR 级别记录消息。
  
  Specified by:
  
  error in interface Logger
  
  Parameters:
  
  messageSupplier - the message supplier - 消息提供者
- error
  
  public void error(Supplier<String> messageSupplier, Throwable throwable)
  
  Logs a message at ERROR level using lazy evaluation with exception. 使用延迟求值和异常在 ERROR 级别记录消息。
  
  Specified by:
  
  error in interface Logger
  
  Parameters:
  
  messageSupplier - the message supplier - 消息提供者
  
  throwable - the exception - 异常
- error
  
  public void error(Marker marker, String message)
  
  Logs a message at ERROR level with a marker. 使用标记在 ERROR 级别记录消息。
  
  Specified by:
  
  error in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  message - the message - 消息
- error
  
  public void error(Marker marker, String format, Object... args)
  
  Logs a message at ERROR level with a marker and parameters. 使用标记和参数在 ERROR 级别记录消息。
  
  Specified by:
  
  error in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- error
  
  public void error(Marker marker, String message, Throwable throwable)
  
  Logs a message at ERROR level with a marker and exception. 使用标记和异常在 ERROR 级别记录消息。
  
  Specified by:
  
  error in interface Logger
  
  Parameters:
  
  marker - the marker - 标记
  
  message - the message - 消息
  
  throwable - the exception - 异常
- log
  
  public void log(LogLevel level, String message)
  
  Logs a message at the specified level. 在指定级别记录消息。
  
  Specified by:
  
  log in interface Logger
  
  Parameters:
  
  level - the log level - 日志级别
  
  message - the message - 消息
- log
  
  public void log(LogLevel level, String format, Object... args)
  
  Logs a message at the specified level with parameters. 在指定级别记录带参数的消息。
  
  Specified by:
  
  log in interface Logger
  
  Parameters:
  
  level - the log level - 日志级别
  
  format - the format string - 格式字符串
  
  args - the arguments - 参数
- log
  
  public void log(LogLevel level, String message, Throwable throwable)
  
  Logs a message at the specified level with an exception. 在指定级别记录带异常的消息。
  
  Specified by:
  
  log in interface Logger
  
  Parameters:
  
  level - the log level - 日志级别
  
  message - the message - 消息
  
  throwable - the exception - 异常

Class AsyncLogger

Method Summary

Methods inherited from class Object

Method Details

wrap

wrap

flush

shutdown

close

getName

isTraceEnabled

isTraceEnabled

isDebugEnabled

isDebugEnabled

isInfoEnabled

isInfoEnabled

isWarnEnabled

isWarnEnabled

isErrorEnabled

isErrorEnabled

isEnabled

trace

trace

trace

trace

trace

trace

debug

debug

debug

debug

debug

debug

info

info

info

info

info

info

warn

warn

warn

warn

warn

warn

warn

error

error

error

error

error

error

error

error

error

log

log

log