Class OpenTelemetryTracer

java.lang.Object
cloud.opencode.base.observability.OpenTelemetryTracer
All Implemented Interfaces:
Tracer
public final class OpenTelemetryTracer extends Object implements Tracer
OpenTelemetry integration for operation tracing with graceful no-op fallback. 用于操作追踪的 OpenTelemetry 集成，支持优雅的空操作回退。

Provides a lightweight abstraction over the OpenTelemetry tracing API that does not directly depend on the OTel SDK. If the OTel API is present on the classpath, it uses reflection to create real spans; otherwise it falls back to no-op transparently.

提供对 OpenTelemetry 追踪 API 的轻量级抽象，不直接依赖 OTel SDK。 如果 OTel API 存在于类路径中，则使用反射创建真实的 span；否则透明地回退到空操作。

Features | 主要功能:

  • Zero-dependency abstraction over OpenTelemetry - 对 OpenTelemetry 的零依赖抽象
  • Automatic classpath detection via reflection - 通过反射自动检测类路径
  • No-op fallback when OTel is not available - OTel 不可用时的空操作回退
  • Thread-safe span creation and attribute setting - 线程安全的 span 创建和属性设置

Usage Examples | 使用示例:

// Auto-detects OTel on classpath; falls back to noop if absent
Tracer tracer = OpenTelemetryTracer.create("my-service");

try (Span span = tracer.startSpan("GET", "user:123")) {
    span.setHit(true);
    span.setAttribute("cache.tier", "L1");
}

tracer.close();

Performance | 性能特性:

  • No-op path has near-zero overhead - 空操作路径几乎零开销
  • Reflection-based method handles cached per class+method - 反射方法句柄按类+方法缓存

Security | 安全性:

  • Thread-safe: Yes (ConcurrentHashMap for cache, AtomicBoolean for state) - 线程安全: 是
  • Null-safe: Yes (rejects null parameters, noop fallback) - 空值安全: 是
Since:
JDK 25, opencode-base-observability V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static OpenTelemetryTracer create(String serviceName)
      Creates an OpenTelemetryTracer for the given service name. 为给定的服务名称创建 OpenTelemetryTracer。

      Attempts to locate the OpenTelemetry API on the classpath via reflection. If unavailable, the returned tracer silently delegates to a no-op implementation.

      尝试通过反射在类路径上定位 OpenTelemetry API。如果不可用，返回的追踪器静默委托给空操作实现。

      Parameters:
      serviceName - the logical service name for tracing | 用于追踪的逻辑服务名称
      Returns:
      a new tracer instance (may be backed by noop) | 新的追踪器实例（可能由 noop 支持）

    • startSpan

      public Span startSpan(String operationName, String key)
      Description copied from interface: Tracer
      Starts a new trace span for the given operation. 为给定的操作启动一个新的追踪 span。
      Specified by:
      startSpan in interface Tracer
      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

      public void close()
      Description copied from interface: Tracer
      Closes this tracer and releases any underlying resources. 关闭此追踪器并释放所有底层资源。
      Specified by:
      close in interface Tracer

    • isOtelAvailable

      public boolean isOtelAvailable()
      Returns whether OpenTelemetry API was detected on the classpath. 返回是否在类路径上检测到 OpenTelemetry API。
      Returns:
      true if OTel is available | 如果 OTel 可用则返回 true

    • serviceName

      public String serviceName()
      Returns the configured service name. 返回配置的服务名称。
      Returns:
      the service name | 服务名称