Pipecat Integration Overview

Add automatic tracing to Pipecat voice pipelines with Noveum Trace

Noveum Trace adds automatic tracing to your Pipecat voice pipeline in minutes. Every conversation is recorded as a structured trace with per-turn spans for STT, LLM, and TTS; tool/function-call details are attached to the LLM span as attributes (when available), along with latency and token usage.

Prerequisites

Python 3.11+
A working Pipecat pipeline (pipecat-ai)
A Noveum API key (get one at noveum.ai)

Installation

pip install "noveum-trace[pipecat]"

Quick Start

You only need three changes:

Initialize noveum_trace once at startup.
Create a NoveumTraceObserver.
Attach the observer to your PipelineTask (and ensure turn tracking wiring happens before the runner starts).

import asyncio
 
import noveum_trace
from noveum_trace.integrations.pipecat import NoveumTraceObserver
 
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.task import PipelineTask
from pipecat.pipeline.runner import PipelineRunner
 
# 1) Initialize noveum-trace once at startup
noveum_trace.init(
    api_key="your-noveum-api-key",
    project="my-voice-bot",
)
 
# --- your existing pipeline setup ---
pipeline = Pipeline([
    transport.input(),
    stt,
    context_aggregator.user(),
    llm,
    tts,
    transport.output(),
    context_aggregator.assistant(),
])
 
async def main():
    # 2) Add NoveumTraceObserver to your PipelineTask
    trace_obs = NoveumTraceObserver()
 
    task = PipelineTask(
        pipeline,
        observers=[trace_obs],
    )
 
    # 3) Wire turn tracking
    await trace_obs.attach_to_task(task)
 
    runner = PipelineRunner()
    await runner.run(task)
 
asyncio.run(main())

Traces are flushed automatically when the pipeline ends (EndFrame / CancelFrame).

What Gets Traced

Each pipeline session produces one conversation trace containing a turn span per conversational exchange. Each turn has child spans for STT, LLM, and TTS. When record_audio=True and an AudioBufferProcessor is present, a full-conversation recording span is also created at the root.

Trace: pipecat.conversation
│   pipeline.allow_interruptions, pipeline.sample_rate
│   conversation.total_input_tokens, conversation.total_output_tokens
│   conversation.total_cost, conversation.turn_count
│
├── Span: pipecat.turn  (one per user→bot exchange)
│   ├── turn.number, turn.user_input, turn.duration_seconds
│   ├── turn.user_bot_latency_seconds  (when latency observer is wired)
│   ├── turn.was_interrupted
│   ├── turn.eou_is_complete, turn.eou_confidence  (SmartTurn, when available)
│   │
│   ├── Span: pipecat.stt
│   │   ├── stt.text, stt.is_final, stt.language, stt.user_id
│   │   ├── stt.model, stt.confidence
│   │   ├── stt.vad_to_final_ms, stt.first_text_latency_ms
│   │   ├── stt.interim_results  (JSON list of {text, confidence})
│   │   └── stt.audio_uuid  (when record_audio=True)
│   │
│   ├── Span: pipecat.llm
│   │   ├── llm.model, llm.system_prompt, llm.temperature, llm.max_tokens
│   │   ├── llm.input  (full message history JSON), llm.output
│   │   ├── llm.input_tokens, llm.output_tokens, llm.total_tokens
│   │   ├── llm.cost.input, llm.cost.output, llm.cost.total, llm.cost.currency
│   │   ├── llm.time_to_first_token_ms
│   │   ├── llm.thoughts[], llm.thought_signatures[]  (thinking-enabled models)
│   │   ├── llm.function_calls[], llm.function_call_results[]  (tool calls)
│   │   └── llm.tools, llm.tool_choice  (when set)
│   │
│   └── Span: pipecat.tts
│       ├── tts.input_text, tts.voice, tts.model
│       ├── tts.time_to_first_byte_ms, tts.characters
│       └── tts.audio_uuid  (when record_audio=True)
│
└── Span: pipecat.full_conversation  (when record_audio=True + AudioBufferProcessor in pipeline)
    └── full_conversation.audio_uuid, full_conversation.audio_format
        full_conversation.audio_channels, full_conversation.duration_ms
        full_conversation.sample_rate
        (stereo WAV: left channel = user, right channel = bot)

Configuration Options

trace_obs = NoveumTraceObserver(
    trace_name_prefix="pipecat",   # produces trace named "pipecat.conversation"
    capture_text=True,             # capture LLM input/output and TTS text in spans
    capture_function_calls=True,   # record tool calls on the pipecat.llm span
    record_audio=True,             # upload per-span STT/TTS audio + full conversation WAV
)

Common tweaks:

Turn off capture_text if you want less text stored in spans.
Set capture_function_calls=False if your LLM never emits function-call frames.
record_audio=True does two things:
- Uploads per-span audio and adds stt.audio_uuid / tts.audio_uuid attributes.
- Captures a full stereo conversation WAV as a pipecat.full_conversation span. This requires AudioBufferProcessor(num_channels=2) to be present in your pipeline (see the basic example).

You can also use the convenience factory instead of constructing NoveumTraceObserver directly:

from noveum_trace.integrations.pipecat import setup_pipecat_tracing
 
trace_obs = setup_pipecat_tracing(record_audio=True)

Troubleshooting

No traces appearing

Verify noveum_trace.init() is called before the pipeline starts.
Confirm await trace_obs.attach_to_task(task) is called (from async code) after PipelineTask is constructed and before runner.run(task).
Confirm your API key and the project name match what you configured in the Noveum dashboard.

Turn spans missing or not splitting correctly

await trace_obs.attach_to_task(task) is required for accurate turn boundaries.
Ensure turn tracking is enabled in your Pipecat version so attach_to_task() can wire external boundaries.

LLM token counts not appearing

Confirm PipelineParams(enable_metrics=True, enable_usage_metrics=True) is set on your PipelineTask — Pipecat only emits MetricsFrame when metrics are enabled.
Token counts come from Pipecat's MetricsFrame. Most standard Pipecat LLM services emit them when metrics are enabled.

Function call spans missing

Set capture_function_calls=True.
Confirm your LLM processor emits FunctionCallInProgressFrame / FunctionCallResultFrame.

Next Steps

Explore a complete example: Basic Pipecat Voice Pipeline