Package com.tnsai.quality.observability

Class TraceContext

java.lang.Object
com.tnsai.quality.observability.TraceContext
public final class TraceContext extends Object
Distributed tracing context for tracking operations across agents.

TraceContext follows the W3C Trace Context specification principles, providing correlation IDs that can be propagated across agent boundaries.

Key concepts:

  • Trace ID - Unique identifier for the entire trace (request flow)
  • Span ID - Unique identifier for a single operation within the trace
  • Parent Span ID - Links child spans to their parent
  • Baggage - Key-value pairs propagated along the trace

Example usage: 

 // Create root trace (at entry point)
 TraceContext trace = TraceContext.newTrace();

 // Create child span for nested operation
 TraceContext childSpan = trace.createChildSpan("processAction");

 // Add baggage (propagated to all child spans)
 trace.setBaggage("userId", "user-123");

 // Use with structured logging
 logger.info("Processing request", trace.toLogContext());

 // Record timing
 childSpan.recordDuration();

Thread-local context for automatic propagation: 

 TraceContext.setCurrent(trace);
 // ... nested calls can access via TraceContext.current()
 TraceContext current = TraceContext.current();
See Also:

  • Method Details

    • newTrace

      public static TraceContext newTrace()
      Creates a new root trace context.
      Returns:
      a new trace context with generated IDs

    • newTrace

      public static TraceContext newTrace(String operationName)
      Creates a new root trace context with an operation name.
      Parameters:
      operationName - the operation name
      Returns:
      a new trace context

    • fromUpstream

      public static TraceContext fromUpstream(String traceId, String parentSpanId, String operationName)
      Creates a trace context from an existing trace ID (for distributed tracing).
      Parameters:
      traceId - the trace ID from upstream service
      parentSpanId - the parent span ID
      operationName - the operation name
      Returns:
      a new span in the existing trace

    • current

      public static TraceContext current()
      Gets the current trace context for this thread.
      Returns:
      the current trace context, or null if none set

    • setCurrent

      public static void setCurrent(TraceContext context)
      Sets the current trace context for this thread.
      Parameters:
      context - the trace context to set

    • clearCurrent

      public static void clearCurrent()
      Clears the current trace context.

    • run

      public void run(Runnable runnable)
      Executes a runnable with this context as current.
      Parameters:
      runnable - the code to execute

    • createChildSpan

      public TraceContext createChildSpan(String operationName)
      Creates a child span for a nested operation.
      Parameters:
      operationName - the child operation name
      Returns:
      a new child span

    • end

      public void end()
      Records the end time and calculates duration.

    • setSuccess

      public void setSuccess()
      Marks the span as successful.

    • setError

      public void setError(String message)
      Marks the span as failed with an error message.
      Parameters:
      message - the error message

    • setError

      public void setError(Throwable exception)
      Marks the span as failed with an exception.
      Parameters:
      exception - the exception that caused the failure

    • setBaggage

      public void setBaggage(String key, String value)
      Sets a baggage item (propagated to child spans).
      Parameters:
      key - the baggage key
      value - the baggage value

    • getBaggage

      public String getBaggage(String key)
      Gets a baggage item.
      Parameters:
      key - the baggage key
      Returns:
      the value, or null if not set

    • getAllBaggage

      public Map<String,String> getAllBaggage()
      Gets all baggage items.
      Returns:
      unmodifiable map of baggage

    • setAttribute

      public void setAttribute(String key, Object value)
      Sets an attribute on this span (not propagated).
      Parameters:
      key - the attribute key
      value - the attribute value

    • getAttribute

      public Object getAttribute(String key)
      Gets an attribute value.
      Parameters:
      key - the attribute key
      Returns:
      the value, or null if not set

    • getAttributes

      public Map<String,Object> getAttributes()
      Gets all attributes.
      Returns:
      unmodifiable map of attributes

    • getTraceId

      public String getTraceId()

    • getSpanId

      public String getSpanId()

    • getParentSpanId

      public String getParentSpanId()

    • getOperationName

      public String getOperationName()

    • getStartTime

      public Instant getStartTime()

    • getEndTime

      public Instant getEndTime()

    • getStatus

      public TraceContext.SpanStatus getStatus()

    • getStatusMessage

      public String getStatusMessage()

    • getDurationMs

      public long getDurationMs()
      Gets the duration in milliseconds.
      Returns:
      duration in ms, or -1 if not ended

    • isRoot

      public boolean isRoot()
      Checks if this is a root span (no parent).
      Returns:
      true if root span

    • toLogContext

      public Map<String,String> toLogContext()
      Creates a map suitable for structured logging (MDC).
      Returns:
      map with trace context fields

    • toTraceParent

      public String toTraceParent()
      Creates a W3C traceparent header value.
      Returns:
      traceparent header value

    • fromTraceParent

      public static TraceContext fromTraceParent(String traceparent, String operationName)
      Parses a W3C traceparent header.
      Parameters:
      traceparent - the header value
      operationName - the operation name for the new span
      Returns:
      a new trace context, or null if parsing fails

    • toString

      public String toString()
      Overrides:
      toString in class Object