Class ScopedLogContext

java.lang.Object
cloud.opencode.base.log.enhance.ScopedLogContext
public final class ScopedLogContext extends Object
Scoped Log Context - JDK 25+ ScopedValue-based Context 作用域日志上下文 - 基于 JDK 25+ ScopedValue 的上下文

Provides log context management using ScopedValue, which is more efficient and suitable for Virtual Threads than traditional ThreadLocal-based MDC.

使用 ScopedValue 提供日志上下文管理，比传统基于 ThreadLocal 的 MDC 更高效且更适合虚拟线程。

Advantages over ThreadLocal | 相比 ThreadLocal 的优势:

  • Automatic inheritance to child Virtual Threads - 自动继承到子虚拟线程
  • Immutable within scope - 作用域内不可变
  • No explicit cleanup needed - 无需显式清理
  • Better performance with Virtual Threads - 虚拟线程性能更好

Usage Example | 使用示例:

// Bind and run
ScopedLogContext.where(ScopedLogContext.TRACE_ID, "trace-123")
    .and(ScopedLogContext.USER_ID, "user-456")
    .run(() -> {
        // Context is available here
        OpenLog.info("Processing request");

        // Nested scope
        ScopedLogContext.where(ScopedLogContext.REQUEST_ID, "req-789")
            .run(() -> {
                OpenLog.info("Nested processing");
            });
    });

Features | 主要功能:

  • ScopedValue-based context (JDK 25+) - 基于 ScopedValue 的上下文（JDK 25+）
  • Automatic inheritance to child virtual threads - 自动继承到子虚拟线程
  • Immutable within scope, no cleanup needed - 作用域内不可变，无需清理
  • Fluent carrier API for multiple bindings - 流式载体 API 支持多个绑定

Security | 安全性:

  • Thread-safe: Yes (ScopedValue is inherently thread-safe) - 线程安全: 是（ScopedValue 本身线程安全）
  • Null-safe: No (throws on null bindings) - 空值安全: 否（null 绑定抛异常）
Since:
JDK 25, opencode-base-log V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Details

    • TRACE_ID

      public static final ScopedValue<String> TRACE_ID
      Trace ID for distributed tracing 分布式追踪的追踪 ID

    • USER_ID

      public static final ScopedValue<String> USER_ID
      User ID for user identification 用户标识的用户 ID

    • REQUEST_ID

      public static final ScopedValue<String> REQUEST_ID
      Request ID for request tracking 请求追踪的请求 ID

    • TENANT_ID

      public static final ScopedValue<String> TENANT_ID
      Tenant ID for multi-tenant applications 多租户应用的租户 ID

    • SESSION_ID

      public static final ScopedValue<String> SESSION_ID
      Session ID for session tracking 会话追踪的会话 ID

    • SPAN_ID

      public static final ScopedValue<String> SPAN_ID
      Span ID for distributed tracing spans 分布式追踪跨度的跨度 ID

    • OPERATION

      public static final ScopedValue<String> OPERATION
      Operation name for current operation 当前操作的操作名

  • Method Details

    • where

      public static ScopedLogContext.Carrier where(ScopedValue<String> key, String value)
      Creates a carrier with a single binding 创建带单个绑定的载体
      Parameters:
      key - the scoped value key | 作用域值键
      value - the value to bind | 要绑定的值
      Returns:
      carrier for chaining | 用于链式调用的载体

    • where

      public static ScopedLogContext.Carrier where(Map<ScopedValue<String>, String> bindings)
      Creates a carrier with multiple bindings from a map 从映射创建带多个绑定的载体
      Parameters:
      bindings - the key-value bindings | 键值绑定
      Returns:
      carrier for chaining | 用于链式调用的载体

    • run

      public static void run(String traceId, String userId, Runnable task)
      Runs a task with trace ID and user ID 使用追踪 ID 和用户 ID 运行任务
      Parameters:
      traceId - the trace ID | 追踪 ID
      userId - the user ID | 用户 ID
      task - the task to run | 要运行的任务

    • call

      public static <T> T call(String traceId, String userId, Callable<T> task) throws Exception
      Calls a task with trace ID and user ID 使用追踪 ID 和用户 ID 调用任务
      Type Parameters:
      T - the result type | 结果类型
      Parameters:
      traceId - the trace ID | 追踪 ID
      userId - the user ID | 用户 ID
      task - the task to call | 要调用的任务
      Returns:
      the result | 结果
      Throws:
      Exception - if task fails | 如果任务失败

    • getTraceId

      public static String getTraceId()
      Gets the current trace ID 获取当前追踪 ID
      Returns:
      trace ID or null if not set | 追踪 ID，未设置时返回 null

    • getUserId

      public static String getUserId()
      Gets the current user ID 获取当前用户 ID
      Returns:
      user ID or null if not set | 用户 ID，未设置时返回 null

    • getRequestId

      public static String getRequestId()
      Gets the current request ID 获取当前请求 ID
      Returns:
      request ID or null if not set | 请求 ID，未设置时返回 null

    • getTenantId

      public static String getTenantId()
      Gets the current tenant ID 获取当前租户 ID
      Returns:
      tenant ID or null if not set | 租户 ID，未设置时返回 null

    • getSessionId

      public static String getSessionId()
      Gets the current session ID 获取当前会话 ID
      Returns:
      session ID or null if not set | 会话 ID，未设置时返回 null

    • getSpanId

      public static String getSpanId()
      Gets the current span ID 获取当前跨度 ID
      Returns:
      span ID or null if not set | 跨度 ID，未设置时返回 null

    • getOperation

      public static String getOperation()
      Gets the current operation name 获取当前操作名
      Returns:
      operation name or null if not set | 操作名，未设置时返回 null

    • get

      public static Optional<String> get(ScopedValue<String> key)
      Gets a value as Optional 获取值作为 Optional
      Parameters:
      key - the scoped value key | 作用域值键
      Returns:
      optional containing value or empty | 包含值的 Optional 或空