Interface Span

All Superinterfaces:
AutoCloseable
public interface Span extends AutoCloseable
Represents a single trace span for an operation, supporting AutoCloseable for try-with-resources. 表示单个操作的追踪 span，支持 AutoCloseable 以便使用 try-with-resources。

Provides methods to record hit/miss status, errors, and custom attributes. Implementations must be thread-safe and must tolerate multiple calls to end() or close() (idempotent).

提供记录命中/未命中状态、错误和自定义属性的方法。 实现必须是线程安全的，并且必须容忍对 end() 或 close() 的多次调用（幂等）。

Features | 主要功能:

  • Hit/miss recording - 命中/未命中记录
  • Error capture - 错误捕获
  • Custom string attribute support - 自定义字符串属性支持
  • Idempotent end/close semantics - 幂等的 end/close 语义
  • Shared NOOP singleton for zero-overhead fallback - 共享 NOOP 单例

Usage Examples | 使用示例:

try (Span span = tracer.startSpan("GET", "user:123")) {
    Object value = cache.get("user:123");
    span.setHit(value != null);
    span.setAttribute("cache.tier", "L1");
} catch (Exception e) {
    span.setError(e);
    throw e;
}

Performance | 性能特性:

  • NOOP: zero allocation, constant singleton - NOOP: 零分配，常量单例
  • All operations: O(1) - 所有操作: O(1)

Security | 安全性:

  • Thread-safe: Yes (implementations must be thread-safe, NOOP is stateless) - 线程安全: 是
  • Null-safe: No (attribute key/value must not be null) - 空值安全: 否
Since:
JDK 25, opencode-base-observability V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Span
    NOOP
    A shared no-op Span instance with zero overhead.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes this span by calling end().
    void
    end()
    Ends this span, recording its duration.
    void
    setAttribute(String key, String value)
    Sets a custom string attribute on this span.
    void
    setError(Throwable error)
    Records an error that occurred during this operation.
    void
    setHit(boolean hit)
    Records whether this operation was a hit or a miss.

  • Field Details

    • NOOP

      static final Span NOOP
      A shared no-op Span instance with zero overhead. 共享的零开销空操作 Span 实例。

  • Method Details

    • setHit

      void setHit(boolean hit)
      Records whether this operation was a hit or a miss. 记录此操作是命中还是未命中。
      Parameters:
      hit - true if the key was found, false otherwise | 如果键被找到则为 true

    • setError

      void setError(Throwable error)
      Records an error that occurred during this operation. 记录此操作期间发生的错误。
      Parameters:
      error - the throwable that occurred | 发生的异常

    • setAttribute

      void setAttribute(String key, String value)
      Sets a custom string attribute on this span. 在此 span 上设置自定义字符串属性。
      Parameters:
      key - the attribute key | 属性键
      value - the attribute value | 属性值

    • end

      void end()
      Ends this span, recording its duration. Must be idempotent. 结束此 span，记录其持续时间。必须是幂等的。

    • close

      void close()
      Closes this span by calling end(). 通过调用 end() 关闭此 span。
      Specified by:
      close in interface AutoCloseable