> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.comet.com/docs/opik/_mcp/server.

# Observability for Pipecat with Opik

> Start here to integrate Opik into your Pipecat-based real-time voice agent application for end-to-end LLM observability, unit testing, and optimization.

[Pipecat](https://github.com/pipecat-ai/pipecat) is an open-source Python framework for building real-time voice and multimodal conversational AI agents. Developed by Daily, it enables fully programmable AI voice agents and supports multimodal interactions, positioning itself as a flexible solution for developers looking to build conversational AI systems.

This guide explains how to integrate Opik with Pipecat for observability and tracing of real-time voice agents, enabling you to monitor, debug, and optimize your Pipecat agents in the Opik dashboard.

## Account Setup

[Comet](https://www.comet.com/site?from=llm\&utm_source=opik\&utm_medium=colab\&utm_content=pipecat\&utm_campaign=opik) provides a hosted version of the Opik platform, [simply create an account](https://www.comet.com/signup?from=llm\&utm_source=opik\&utm_medium=colab\&utm_content=pipecat\&utm_campaign=opik) and grab your API Key.

> You can also run the Opik platform locally, see the [installation guide](https://www.comet.com/docs/opik/self-host/overview/?from=llm\&utm_source=opik\&utm_medium=colab\&utm_content=pipecat\&utm_campaign=opik) for more information.

![](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/opik.docs.buildwithfern.com/e0255a70fb119731e60c84d4c71070dec37476872a69213e4b3f5714246ed7e4/img/tracing/pipecat_integration.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260922%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260922T031532Z&X-Amz-Expires=604800&X-Amz-Signature=25e2040005bb9959e1f5360d6c06a5a9459c34024e5c16ee1ab7c4c5c2c732ce&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Getting started

To use the Pipecat integration with Opik, you will need to have Pipecat and the required OpenTelemetry packages installed:

```bash
pip install pipecat-ai[daily,webrtc,silero,cartesia,deepgram,openai,tracing] opentelemetry-exporter-otlp-proto-http websockets
```

#### Opik Cloud

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT=https://www.comet.com/opik/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default'
```

#### Enterprise deployment

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<comet-deployment-url>/opik/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default'
```

#### Self-hosted instance

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5173/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='projectName=<your-project-name>'
```

## Using Opik with Pipecat

For the basic example, you'll need an OpenAI API key. You can set it as an environment variable:

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
```

Or set it programmatically:

```python
import os
import getpass

if "OPENAI_API_KEY" not in os.environ:
    os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")
```

Enable tracing in your Pipecat application by setting up OpenTelemetry instrumentation and configuring your pipeline task. For complete details on Pipecat's OpenTelemetry implementation, see the [official Pipecat OpenTelemetry documentation](https://docs.pipecat.ai/server/utilities/opentelemetry):

```python
# Initialize OpenTelemetry with the http exporter
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from pipecat.utils.tracing.setup import setup_tracing

# Configured automatically from .env
exporter = OTLPSpanExporter()

setup_tracing(
    service_name="pipecat-demo",
    exporter=exporter,
)

# Enable tracing in your PipelineTask
task = PipelineTask(
    pipeline,
    params=PipelineParams(
        allow_interruptions=True,
        enable_metrics=True,  # Required for some service metrics
    ),
    enable_tracing=True,  # Enables both turn and conversation tracing
    conversation_id="customer-123",  # Optional - will auto-generate if not provided
)
```

## Trace Structure

Pipecat organizes traces hierarchically following the natural structure of conversations, as documented in their [OpenTelemetry guide](https://docs.pipecat.ai/server/utilities/opentelemetry):

```
Conversation (conversation_id)
├── turn
│   ├── stt (Speech-to-Text)
│   ├── llm (Language Model)
│   └── tts (Text-to-Speech)
└── turn
    ├── stt
    ├── llm
    └── tts
```

This structure allows you to track the complete lifecycle of conversations and measure latency for individual turns and services.

## Understanding the Traces

Based on Pipecat's [OpenTelemetry implementation](https://docs.pipecat.ai/server/utilities/opentelemetry), the traces include:

* **Conversation Spans**: Top-level spans with conversation ID and type
* **Turn Spans**: Individual conversation turns with turn number, duration, and interruption status
* **Service Spans**: Detailed service operations with rich attributes:
  * **LLM Services**: Model, input/output tokens, response text, tool configurations, TTFB metrics
  * **TTS Services**: Voice ID, character count, synthesized text, TTFB metrics
  * **STT Services**: Transcribed text, language detection, voice activity detection
* **Performance Metrics**: Time to first byte (TTFB) and processing durations for each service

## Results viewing

Once your Pipecat applications are traced with Opik, you can view the OpenTelemetry traces in the Opik UI. You will see:

* Hierarchical conversation and turn structure as sent by Pipecat
* Service-level spans with the attributes Pipecat includes (LLM tokens, TTS character counts, STT transcripts)
* Performance metrics like processing durations and time-to-first-byte where provided by Pipecat
* Standard OpenTelemetry trace visualization and search capabilities

### Getting Help

* Check the [Pipecat OpenTelemetry Documentation](https://docs.pipecat.ai/server/utilities/opentelemetry) for tracing setup and configuration
* Review the [OpenTelemetry Python Documentation](https://opentelemetry.io/docs/instrumentation/python/) for general OTEL setup
* Visit the [Pipecat GitHub repository](https://github.com/pipecat-ai/pipecat) for framework-specific issues
* Check Opik documentation for trace viewing and OpenTelemetry endpoint configuration

## Further improvements

If you would like to see us improve this integration, simply open a new feature
request on [Github](https://github.com/comet-ml/opik/issues).