Class ObservabilityContext

java.lang.Object
cloud.opencode.base.observability.context.ObservabilityContext
public final class ObservabilityContext extends Object
Thread-local observability context carrying trace ID, span ID, and baggage. 携带 trace ID、span ID 和 baggage 的线程局部可观测性上下文。

Provides context propagation across threads via wrap(Runnable) and wrap(Callable). The attach() method sets this context as the current thread's context, returning a ObservabilityContext.Scope that restores the previous context when closed. Contexts are immutable; methods like withSpanId(String) and withBaggage(String, String) return new instances.

通过 wrap(Runnable) 和 wrap(Callable) 提供跨线程的上下文传播。 attach() 方法将此上下文设置为当前线程的上下文， 返回一个在关闭时恢复先前上下文的 ObservabilityContext.Scope。上下文是不可变的； withSpanId(String) 和 withBaggage(String, String) 等方法返回新实例。

Since:
JDK 25, opencode-base-observability V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • current

      public static ObservabilityContext current()
      Returns the current thread's observability context, or null if none is attached. 返回当前线程的可观测性上下文，如果没有附加则返回 null。

      Null-safety | 空值安全: This method may return null. Always check before use to avoid NullPointerException:

      ObservabilityContext ctx = ObservabilityContext.current();
if (ctx != null) {
    String traceId = ctx.traceId();
}

      此方法可能返回 null，使用前请检查。

      Returns:
      the current context, or null | 当前上下文，或 null

    • create

      public static ObservabilityContext create(String traceId)
      Creates a new context with the given trace ID and an auto-generated span ID. 使用给定的 trace ID 和自动生成的 span ID 创建新上下文。
      Parameters:
      traceId - the trace identifier | 追踪标识符
      Returns:
      a new context | 新上下文
      Throws:
      ObservabilityException - if traceId is null or blank | 如果 traceId 为 null 或空白

    • create

      public static ObservabilityContext create(String traceId, String spanId)
      Creates a new context with the given trace ID and span ID. 使用给定的 trace ID 和 span ID 创建新上下文。
      Parameters:
      traceId - the trace identifier | 追踪标识符
      spanId - the span identifier | span 标识符
      Returns:
      a new context | 新上下文
      Throws:
      ObservabilityException - if traceId or spanId is null or blank | 如果 traceId 或 spanId 为 null 或空白

    • clear

      public static void clear()
      Clears the current thread's observability context. 清除当前线程的可观测性上下文。

    • traceId

      public String traceId()
      Returns the trace ID. 返回 trace ID。
      Returns:
      the trace identifier | 追踪标识符

    • spanId

      public String spanId()
      Returns the span ID. 返回 span ID。
      Returns:
      the span identifier | span 标识符

    • baggage

      public Optional<String> baggage(String key)
      Returns the baggage value for the given key. 返回给定键的 baggage 值。
      Parameters:
      key - the baggage key (null returns empty) | baggage 键（null 返回空）
      Returns:
      an Optional containing the value, or empty | 包含值的 Optional，或空

    • allBaggage

      public Map<String,String> allBaggage()
      Returns all baggage as an unmodifiable map. 以不可修改映射返回所有 baggage。
      Returns:
      the baggage map | baggage 映射

    • withSpanId

      public ObservabilityContext withSpanId(String newSpanId)
      Returns a new context with the same trace ID and baggage but a different span ID. 返回具有相同 trace ID 和 baggage 但不同 span ID 的新上下文。
      Parameters:
      newSpanId - the new span identifier | 新的 span 标识符
      Returns:
      a new context with the updated span ID | 带有更新后 span ID 的新上下文
      Throws:
      ObservabilityException - if newSpanId is null or blank | 如果 newSpanId 为 null 或空白

    • withBaggage

      public ObservabilityContext withBaggage(String key, String value)
      Returns a new context with an additional baggage entry. 返回带有额外 baggage 条目的新上下文。
      Parameters:
      key - the baggage key | baggage 键
      value - the baggage value | baggage 值
      Returns:
      a new context with the added baggage | 带有添加的 baggage 的新上下文
      Throws:
      ObservabilityException - if key is null/blank or value is null | 如果 key 为 null/空白或 value 为 null

    • attach

      public ObservabilityContext.Scope attach()
      Attaches this context to the current thread, returning a ObservabilityContext.Scope that restores the previous context when closed. 将此上下文附加到当前线程，返回一个在关闭时恢复先前上下文的 ObservabilityContext.Scope。

      Security note | 安全注意事项: The returned ObservabilityContext.Scope must be closed (preferably via try-with-resources) to prevent context leakage across requests in thread pools. Failing to close the Scope leaves sensitive baggage values (e.g., user.id, session.token) on the thread, where they may be inherited by the next task reusing the same thread.

      返回的 ObservabilityContext.Scope 必须关闭（推荐使用 try-with-resources），以防止在线程池中 上下文跨请求泄漏。未关闭 Scope 会导致敏感 baggage 值（如 user.id、session.token） 残留在线程上，可能被复用该线程的下一个任务继承。

      // Correct usage | 正确用法:
try (ObservabilityContext.Scope scope = ctx.attach()) {
    // ... work ...
} // context automatically restored | 上下文自动恢复
      Returns:
      a scope that must be closed to restore the previous context | 必须关闭以恢复先前上下文的 scope

    • wrap

      public Runnable wrap(Runnable task)
      Wraps a Runnable to propagate this context when executed. 包装 Runnable 以在执行时传播此上下文。
      Parameters:
      task - the task to wrap | 要包装的任务
      Returns:
      a wrapped runnable that propagates this context | 传播此上下文的包装 runnable
      Throws:
      ObservabilityException - if task is null | 如果 task 为 null

    • wrap

      public <T> Callable<T> wrap(Callable<T> task)
      Wraps a Callable to propagate this context when executed. 包装 Callable 以在执行时传播此上下文。
      Type Parameters:
      T - the callable return type | callable 返回类型
      Parameters:
      task - the task to wrap | 要包装的任务
      Returns:
      a wrapped callable that propagates this context | 传播此上下文的包装 callable
      Throws:
      ObservabilityException - if task is null | 如果 task 为 null

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object