service_decorators

Service-specific OpenTelemetry tracing decorators for Pipecat.

This module provides specialized decorators that automatically capture rich information about service execution including configuration, parameters, and performance metrics.

pipecat.utils.tracing.service_decorators.traced_tts(func: Callable | None = None, *, name: str | None = None) → Callable

Trace TTS service methods with TTS-specific attributes.

Automatically captures and records:

• Service name and model information

• Voice ID and settings

• Character count and text content

• Performance metrics like TTFB

The span is scoped to the full synthesis operation, from create_audio_context until TTSStoppedFrame (or remove_audio_context as a safety net), so TTFB and any other runtime-computed metrics land on the correct span even when audio chunks are delivered after run_tts returns (e.g. WebSocket streaming TTS services).

Works with both async functions and generators.

Parameters:

• func – The TTS method to trace.

• name – Custom span name. Defaults to service type and class name.

Returns:

Wrapped method with TTS-specific tracing.

pipecat.utils.tracing.service_decorators.traced_stt(func: Callable | None = None, *, name: str | None = None) → Callable

Trace STT service methods with transcription attributes.

Automatically captures and records:

• Service name and model information

• Transcription text and final status

• Language information

• Performance metrics like TTFB

• Usage metrics (audio seconds) when the service reports them via start_stt_usage_metrics

The span is scoped to one STT segment, from VADUserStartedSpeakingFrame (or the first TranscriptionFrame when VAD did not fire, e.g. whispered speech) until a finalized TranscriptionFrame. Multiple finalized transcripts in a single user turn produce multiple sequential spans, each anchored at the point speech for that segment began. metrics.ttfb is read after the base push_frame runs stop_ttfb_metrics for the finalized frame, so the value is correct for the closing span.

Parameters:

• func – The STT method to trace.

• name – Custom span name. Defaults to function name.

Returns:

The original method unchanged. The decorator’s class-definition- time work is to install a push_frame wrapper on the owning class that owns the span lifetime.

pipecat.utils.tracing.service_decorators.traced_llm(func: Callable | None = None, *, name: str | None = None) → Callable

Trace LLM service methods with LLM-specific attributes.

Automatically captures and records:

• Service name and model information

• Context content and messages

• Tool configurations

• Token usage metrics

• Performance metrics like TTFB

• Aggregated output text

Parameters:

• func – The LLM method to trace.

• name – Custom span name. Defaults to service type and class name.

Returns:

Wrapped method with LLM-specific tracing.

pipecat.utils.tracing.service_decorators.traced_gemini_live(operation: str) → Callable

Trace Gemini Live service methods with operation-specific attributes.

This decorator automatically captures relevant information based on the operation type:

• llm_setup: Configuration, tools definitions, and system instructions

• llm_tool_call: Function call information

• llm_tool_result: Function execution results

• llm_response: Complete LLM response with usage and output

Parameters:

operation – The operation name (matches the event type being handled).

Returns:

Wrapped method with Gemini Live specific tracing.

pipecat.utils.tracing.service_decorators.traced_openai_realtime(operation: str) → Callable

Trace OpenAI Realtime service methods with operation-specific attributes.

This decorator automatically captures relevant information based on the operation type:

• llm_setup: Session configuration and tools

• llm_request: Context and input messages

• llm_response: Usage metadata, output, and function calls

Parameters:

operation – The operation name (matches the event type being handled).

Returns:

Wrapped method with OpenAI Realtime specific tracing.