Interface Tracer

All Known Implementing Classes:
OpenTelemetryTracer, Tracer.NoopTracer
public sealed interface Tracer permits OpenTelemetryTracer, Tracer.NoopTracer
Framework-agnostic tracing abstraction for creating Span instances around operations. 框架无关的追踪抽象，用于围绕操作创建 Span 实例。

Provides a uniform API for operation tracing. Implementations may delegate to OpenTelemetry, other tracing frameworks, or a no-op fallback. The sealed interface restricts permitted implementations to known, auditable types.

提供统一的操作追踪 API。实现可以委托给 OpenTelemetry、其他追踪框架或空操作回退。 密封接口将允许的实现限制为已知的、可审计的类型。

Features | 主要功能:

  • Framework-agnostic tracing API - 框架无关的追踪 API
  • OpenTelemetry integration via reflection (no hard dependency) - 通过反射集成 OpenTelemetry
  • Zero-overhead no-op implementation - 零开销的空操作实现
  • try-with-resources support via AutoCloseable spans - 通过 AutoCloseable span 支持 try-with-resources

Usage Examples | 使用示例:

Tracer tracer = OpenTelemetryTracer.create("my-service");
try (Span span = tracer.startSpan("GET", "user:42")) {
    Object value = cache.get("user:42");
    span.setHit(value != null);
}
tracer.close();

Performance | 性能特性:

  • No-op: zero allocation, zero overhead - 空操作: 零分配，零开销
  • OTel: reflection-based with cached method handles - OTel: 基于反射，缓存方法句柄

Security | 安全性:

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

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    Tracer.NoopTracer
    No-op implementation of Tracer with zero overhead.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Closes this tracer and releases any underlying resources.
    static Tracer
    noop()
    Returns a no-op Tracer that creates no-op spans with zero overhead.
    Span
    startSpan(String operationName, String key)
    Starts a new trace span for the given operation.

  • Method Details

    • startSpan

      Span startSpan(String operationName, String key)
      Starts a new trace span for the given operation. 为给定的操作启动一个新的追踪 span。
      Parameters:
      operationName - the name of the operation (e.g., "GET", "PUT") | 操作名称（例如 "GET"、"PUT"）
      key - the key or resource being operated on | 被操作的键或资源
      Returns:
      a new Span representing this operation | 代表此操作的新 Span

    • close

      void close()
      Closes this tracer and releases any underlying resources. 关闭此追踪器并释放所有底层资源。

    • noop

      static Tracer noop()
      Returns a no-op Tracer that creates no-op spans with zero overhead. 返回一个空操作 Tracer，以零开销创建空操作 span。
      Returns:
      the no-op tracer singleton | 空操作追踪器单例