TurnTraceObserver

class pipecat.utils.tracing.turn_trace_observer.TurnTraceObserver(turn_tracker, conversation_id=None, additional_span_attributes=None, **kwargs)

Bases: BaseObserver

Observer that creates trace spans for each conversation turn.

This observer uses TurnTrackingObserver to track turns and creates OpenTelemetry spans for each turn. Service spans (STT, LLM, TTS) become children of the turn spans.

If conversation tracing is enabled, turns become children of a conversation span that encapsulates the entire session.

Parameters:

• turn_tracker (TurnTrackingObserver)

• conversation_id (str | None)

• additional_span_attributes (dict | None)

async on_push_frame(data)

Process a frame without modifying it.

This observer doesn’t need to process individual frames as it relies on turn start/end events from the turn tracker.

Parameters:

data (FramePushed)

start_conversation_tracing(conversation_id=None)

Start a new conversation span.

Parameters:

conversation_id (str | None) – Optional custom ID for the conversation. If None, a UUID will be generated.

end_conversation_tracing()

End the current conversation span and ensure the last turn is closed.

get_current_turn_context()

Get the span context for the current turn.

This can be used by services to create child spans.

Return type:

SpanContext | None

get_turn_context(turn_number)

Get the span context for a specific turn.

This can be used by services to create child spans.

Parameters:

turn_number (int)

Return type:

SpanContext | None