Package ai.acolite.agentsdk.core.tracing

Class TraceContext

java.lang.Object
ai.acolite.agentsdk.core.tracing.TraceContext
public class TraceContext extends Object
TraceContext

ThreadLocal-based context management for traces and spans. Provides API for tracking the current trace and span within a thread.

Key Features: - ThreadLocal storage for trace/span state - Helper methods for async context propagation - Automatic cleanup with try-finally patterns

Context Propagation: CompletableFuture callbacks run on arbitrary threads and lose ThreadLocal context. Use the provided helper methods (supplyAsync, runAsync) for automatic propagation.

Example: 

 Trace trace = Trace.builder()...build();
 TraceContext.withTrace(trace, () -> {
     // This code runs with trace context
     return doWork();
 });
Source: https://github.com/openai/openai-agents-js/blob/main/packages/agents-core/src/tracing/context.ts

  • Constructor Details

    • TraceContext

      public TraceContext()

  • Method Details

    • getCurrentTrace

      public static Optional<Trace> getCurrentTrace()
      Get the current trace from ThreadLocal storage

    • getCurrentSpan

      public static Optional<Span<?>> getCurrentSpan()
      Get the current span from ThreadLocal storage

    • setCurrentSpan

      public static void setCurrentSpan(Span<?> span)
      Set the current span in the context. The span maintains a reference to the previous span for stack tracking.

    • withTrace

      public static <T> T withTrace(Trace trace, Supplier<T> action)
      Run synchronous code within a trace context. Automatically starts and ends the trace.
      Parameters:
      trace - The trace to set as current
      action - The code to run within the trace
      Returns:
      The result of the action

    • withTraceAsync

      public static <T> CompletableFuture<T> withTraceAsync(Trace trace, Supplier<CompletableFuture<T>> action)
      Run asynchronous code within a trace context. Automatically starts and ends the trace when the future completes.
      Parameters:
      trace - The trace to set as current
      action - The async code to run within the trace
      Returns:
      CompletableFuture with the result

    • getOrCreateTrace

      public static Trace getOrCreateTrace(String name, TraceProcessor processor)
      Get the current trace, or create a new one if none exists
      Parameters:
      name - Name for the new trace (if created)
      processor - Processor for the new trace (if created)
      Returns:
      The current or newly created trace

    • reset

      public static void reset()
      Reset the ThreadLocal context. Call this in finally blocks to prevent memory leaks.

    • captureState

      public static TraceContextState captureState()
      Capture the current context state for propagation to another thread. Returns a copy of the state to avoid sharing mutable objects.
      Returns:
      Copy of current context state, or null if no context

    • restoreState

      public static void restoreState(TraceContextState state)
      Restore a previously captured context state. Used for propagating context to new threads.
      Parameters:
      state - The state to restore

    • supplyAsync

      public static <T> CompletableFuture<T> supplyAsync(Supplier<T> supplier)
      Create a CompletableFuture that preserves trace context. Use this instead of CompletableFuture.supplyAsync() to maintain context.
      Parameters:
      supplier - The code to run asynchronously
      Returns:
      CompletableFuture with context propagation

    • runAsync

      public static CompletableFuture<Void> runAsync(Runnable runnable)
      Create a CompletableFuture that preserves trace context. Use this instead of CompletableFuture.runAsync() to maintain context.
      Parameters:
      runnable - The code to run asynchronously
      Returns:
      CompletableFuture with context propagation

    • wrapFuture

      public static <T> CompletableFuture<T> wrapFuture(CompletableFuture<T> future)
      Wrap a CompletableFuture to ensure context is restored in continuations. Use this when you have an existing CompletableFuture and want to add context-aware continuations.
      Parameters:
      future - The future to wrap
      Returns:
      The same future (for chaining), but context will be restored in .thenApply(), etc.