OpenTelemetry Tracing with Pipecat

This repository demonstrates OpenTelemetry tracing integration for Pipecat services, with examples for different backends.

Tracing Features in Pipecat

Hierarchical Tracing: Track entire conversations, turns, and service calls
Service Tracing: Detailed spans for TTS, STT, and LLM services with rich context
TTFB Metrics: Capture Time To First Byte metrics for latency analysis
Usage Statistics: Track character counts for TTS and token usage for LLMs

Trace Structure

Traces are organized hierarchically:

Conversation (conversation)
├── turn
│   ├── stt_deepgramsttservice
│   ├── llm_openaillmservice
│   └── tts_cartesiattsservice
└── turn
    ├── stt_deepgramsttservice
    ├── llm_openaillmservice
    └── tts_cartesiattsservice
    turn
    └── ...

This organization helps you track conversation-to-conversation and turn-to-turn interactions.

Available Demos

Demo	Description
Jaeger Tracing	Tracing with Jaeger, an open-source end-to-end distributed tracing system
Langfuse Tracing	Tracing with Langfuse, a specialized platform for LLM observability

Common Requirements

Python 3.10+
Pipecat and its dependencies
API keys for the services used (Deepgram, Cartesia, OpenAI)
The appropriate OpenTelemetry exporters

How Tracing Works

The tracing system consists of:

TurnTrackingObserver: Detects conversation turns
TurnTraceObserver: Creates spans for turns and conversations
Service Decorators: @traced_tts, @traced_stt, @traced_llm for service-specific tracing
Context Providers: Share context between different parts of the pipeline

Getting Started

Choose one of the demos from the table above
Follow the README instructions in the respective directory

Common Troubleshooting

Debugging Traces: Set OTEL_CONSOLE_EXPORT=true to print traces to the console for debugging
Missing Metrics: Check that enable_metrics=True in PipelineParams
API Key Issues: Verify your API keys are set correctly in the .env file

README.md