Class TracingContext

java.lang.Object
com.loomcache.server.tracing.TracingContext
public final class TracingContext extends Object
OpenTelemetry distributed tracing integration for LoomCache.

Architecture

This class provides a thin abstraction over distributed tracing, designed to: - Work with OpenTelemetry when available (via reflection/classloading) - Fall back to SLF4J MDC + ScopedValues when OTel is not available - Support W3C Trace Context format for cross-node propagation - Provide virtual thread-friendly context via ScopedValues

Configuration

TracingContext is configured during CacheNode startup with: - Exporter type: NONE (disabled), CONSOLE, OTLP, JAEGER - Service name: "loomcache" (fixed) - Resource attributes: service.name, service.version, node.id - Sampling rate: 0.0-1.0 (default 1.0, always-on)

Usage

// Create a root span for incoming request
var span = TracingContext.createSpan("cache.get", "root");
try {
    span.setAttribute("key", "myKey");
    span.setAttribute("cache.name", "myMap");
    // ... operation ...
    span.setStatus(Span.Status.OK);
} catch (Exception e) {
    span.recordException(e);
    span.setStatus(Span.Status.ERROR);
} finally {
    span.end();
}

Trace Context Propagation

Trace context is automatically available in MDC and ScopedValues: - traceId: unique identifier for the entire distributed transaction - spanId: unique identifier for this span - parentSpanId: optional reference to parent span - sampled: whether sampling is enabled
Since:
1.0

  • Constructor Details

    • TracingContext

      public TracingContext()

  • Method Details

    • initialize

      public static void initialize(@Nullable TracingConfig config)
      Initialize TracingContext with the given configuration.
      Parameters:
      config - configuration for tracing (may be null to disable)

    • createSpan

      public static TracingContext.Span createSpan(String spanName, String kind)
      Create a new span with the given name and kind.
      Parameters:
      spanName - the span name (e.g., "cache.get", "raft.append_entries") (must not be null)
      kind - the span kind ("root", "internal", "client", "server") (must not be null)
      Returns:
      a new Span
      Throws:
      NullPointerException - if spanName or kind is null

    • withSpan

      public static void withSpan(String spanName, String kind, TracingContext.CheckedRunnable block) throws Exception
      Execute a block of code within a span context. Automatically ends the span when the block completes.
      Parameters:
      spanName - the span name (must not be null)
      kind - the span kind (must not be null)
      block - the code to execute (must not be null)
      Throws:
      Exception - if the block throws
      NullPointerException - if spanName, kind, or block is null

    • withSpan

      public static <T> T withSpan(String spanName, String kind, TracingContext.CheckedSupplier<T> block) throws Exception
      Execute a block of code within a span context and return a result. Automatically ends the span when the block completes.
      Type Parameters:
      T - the type of the result
      Parameters:
      spanName - the span name (must not be null)
      kind - the span kind (must not be null)
      block - the code to execute (must not be null)
      Returns:
      the result of the block
      Throws:
      Exception - if the block throws
      NullPointerException - if spanName, kind, or block is null

    • getCurrentSpan

      public static @Nullable TracingContext.Span getCurrentSpan()
      Get the current active span (from ScopedValue).
      Returns:
      the current span, or null if none is active

    • getCurrentTraceId

      public static @Nullable String getCurrentTraceId()
      Get the current trace ID.
      Returns:
      the trace ID, or null if none is active

    • setCurrentSpan

      public static void setCurrentSpan(@Nullable TracingContext.Span span)
      Set the current span (for ScopedValue binding). Typically called internally by withSpan(); direct use is rare.
      Parameters:
      span - the span to set

    • setCurrentTraceId

      public static void setCurrentTraceId(@Nullable String traceId)
      Set the current trace ID (for ScopedValue binding).
      Parameters:
      traceId - the trace ID to set

    • extractTraceContext

      public static Map<String,String> extractTraceContext(@Nullable String traceParentHeader)
      Extract trace context from W3C Trace Context format. Format: traceparent: "00-{traceId}-{spanId}-{flags}"
      Parameters:
      traceParentHeader - the traceparent header value (may be null)
      Returns:
      a Map with extracted context (traceId, spanId, parentSpanId, flags)

    • injectTraceContext

      public static @Nullable String injectTraceContext(@Nullable TracingContext.Span span)
      Inject trace context into W3C Trace Context format.
      Parameters:
      span - the span to inject (may be null)
      Returns:
      the traceparent header value, or null if span is null

    • isOpenTelemetryAvailable

      public static boolean isOpenTelemetryAvailable()
      Check if OpenTelemetry is available.
      Returns:
      true if OTel SDK is on the classpath

    • shutdown

      public static void shutdown()
      Shutdown tracing and flush any pending spans. Called during CacheNode shutdown.

    • getMetrics

      public static Map<String,Object> getMetrics()
      Get tracing statistics.
      Returns:
      a Map with metrics