Package ai.acolite.agentsdk.core.tracing

Class Span<TData extends SpanData>

java.lang.Object

ai.acolite.agentsdk.core.tracing.Span<TData>

Direct Known Subclasses:

NoopSpan

public class Span<TData extends SpanData>
extends Object

Represents a timed operation within a trace.

Spans capture individual operations (agent execution, LLM generation, tool calls, etc.) with start/end timestamps, parent relationships, and operation-specific data.

Lifecycle: 1. Create span with builder 2. Call start() to begin timing 3. Execute operation 4. Call end() to finish (or setError() if failed)

Thread-safe: Yes

Ported from TypeScript OpenAI Agents SDK Source: tracing/spans.ts

Constructor Summary

Constructors

Constructor	Description
Span()

Method Summary

Modifier and Type	Method	Description
Span<TData>	clone()	Clone this span with same properties.
void	end()	End the span.
void	setError(SpanError error)	Set error information.
void	setError(Throwable throwable)	Convenience method to set error from Throwable
void	start()	Start the span.
Map<String,Object>	toJson()	Convert to JSON for export.
Span<TData>	withTracingContext(String traceId, String parentId, String tracingApiKey, TraceProcessor processor)	Clone this span with updated tracing context.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Span

public Span()

Method Details

start

public void start()

Start the span. Calls processor.onSpanStart(). Idempotent - multiple calls are safe.

end

public void end()

End the span. Calls processor.onSpanEnd(). Idempotent - multiple calls are safe.

setError

public void setError(SpanError error)

Set error information. Call this before end() when operation fails.

setError

public void setError(Throwable throwable)

Convenience method to set error from Throwable

clone

public Span<TData> clone()

Clone this span with same properties.

Overrides:

clone in class Object

withTracingContext

public Span<TData> withTracingContext(String traceId,
 String parentId,
 String tracingApiKey,
 TraceProcessor processor)

Clone this span with updated tracing context.

Parameters:

traceId - Parent trace identifier

parentId - Parent span identifier

tracingApiKey - Optional API key for trace export

processor - Processor for lifecycle events

Returns:

New span instance with updated tracing context

toJson

public Map<String,Object> toJson()

Convert to JSON for export.