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
│   conversation.barge_in_rate          (interrupted_turns / total_turns, 0.0–1.0)
│   conversation.interrupted_turn_count (raw count of interrupted turns)
│
├── 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)
│   ├── turn.latency.user_turn_secs          (VAD+STT+turn-analyzer wait duration)
│   ├── turn.latency.ttfb.<service>_ms       (per-service TTFB: stt, llm, tts)
│   ├── turn.latency.text_aggregation_ms     (LLM token → first TTS sentence delay)
│   │
│   ├── 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)
│   │   ├── stt.was_cancelled    (True when interrupted before final transcript)
│   │   ├── stt.partial_transcript  (last interim text received before cancellation)
│   │   ├── stt.interim_count    (number of interim results received)
│   │   └── stt.vad_to_cancel_ms (ms from VAD start to cancellation)
│   │
│   ├── 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.

System prompt (llm.system_prompt) not appearing

This attribute is read from the LLM processor's _settings.system_instruction (or _settings.system_prompt) at the time LLMFullResponseStartFrame fires, then falls back to scanning the message history for a role: "system" entry.
If neither source has the value (e.g. you use a custom or pre-cached LLM processor that does not extend Pipecat's BaseLLMService), the attribute will be absent.
Fix: call trace.set_attributes({"llm.system_prompt": YOUR_SYSTEM_PROMPT}) on the active trace before the first turn, or ensure your custom LLM processor emits LLMContextFrame containing the system role message.

STT spans show only pipecat_span_status: cancelled with no transcript

This is expected for interrupted turns — when the user or bot interrupts before STT finishes, the span is closed with cancellation status.
Starting with SDK v1.6.x, cancelled spans also capture stt.partial_transcript (last interim text), stt.interim_count, and stt.vad_to_cancel_ms so partial speech data is not lost.

Latency breakdown (turn.latency.*) not appearing

These attributes come from Pipecat's UserBotLatencyObserver.on_latency_breakdown event. They require:
1. await trace_obs.attach_to_task(task) to be called (wires the latency observer).
2. PipelineParams(enable_metrics=True) to be set on PipelineTask — otherwise TTFB fields in the breakdown are empty.
3. SDK v1.6.x or later (earlier versions only captured the total turn.user_bot_latency_seconds).

User audio missing from full_conversation (mono instead of stereo)

If a custom processor between transport input and AudioBufferProcessor consumes InputAudioRawFrame without re-emitting it downstream, AudioBufferProcessor never receives the user audio. The SDK cannot work around this.
Fix: modify your custom processor to re-emit InputAudioRawFrame after processing it internally, so frames continue downstream to AudioBufferProcessor.

Next Steps

Explore a complete example: Basic Pipecat Voice Pipeline