Pipecat

NoveumPipecatTracer observes a stock Pipecat pipeline. It groups one pipeline session into a conversation trace and records supported turn, STT, LLM, TTS, tool, latency, usage, and error data emitted by Pipecat.

Requirements

• Python 3.11 or later
• an existing working Pipecat 1.x pipeline
• the transport and provider packages already required by that pipeline

Install the tracing integration:

pip install "noveum-trace[pipecat]"

Initialize Noveum Trace

Initialize once when the application starts:

import os

import noveum_trace

noveum_trace.init(
    api_key=os.environ["NOVEUM_API_KEY"],
    project=os.environ["NOVEUM_PROJECT"],
    environment=os.getenv("NOVEUM_ENVIRONMENT", "production"),
    service_version=os.environ["NOVEUM_SERVICE_VERSION"],
)

Instrument each pipeline session

Create a tracer for each call or connection. Use the returned pipeline and task from both integration methods:

from noveum_trace.integrations.pipecat import NoveumPipecatTracer
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask


async def run_call(pipeline, transport):
    tracer = NoveumPipecatTracer(
        record_audio=False,
        record_raw_input_audio=False,
        capture_text=True,
    )
    pipeline = tracer.observe_pipeline(pipeline)
    task = PipelineTask(
        pipeline,
        params=PipelineParams(
            enable_metrics=True,
            enable_usage_metrics=True,
        ),
    )
    task = await tracer.register_task_handlers(task, transport=transport)
    await PipelineRunner().run(task)

observe_pipeline() and register_task_handlers() can modify or replace the supplied object. Discarding either return value loses tracing wiring. Passing transport enables transport-aware session metadata and supported input-audio handling.

Do not reuse one stateful tracer across simultaneous calls. The SDK initialization is process-wide, but conversation and turn state belongs to one pipeline session.

Choose payload capture deliberately

Never send credentials, authorization headers, private keys, or secrets through messages, tool arguments, metadata, or output.

What is captured

One observed pipeline can produce:

• one conversation trace
• one span per detected conversational turn
• STT, LLM, and TTS child spans when corresponding Pipecat frames are emitted
• tool calls and results when function-call frames are emitted
• token usage and latency when Pipecat metrics are enabled and the provider reports them
• interruption, error, and terminal session state
• optional utterance, raw-input, and full-conversation audio

Exact fields depend on the Pipecat version, processors, and providers. Review a representative trace before building ETL logic around optional metrics.

Troubleshooting

If no trace appears:

1. confirm noveum_trace.init() runs before the pipeline session
2. assign both integration return values
3. create a new tracer for the session
4. pass the active transport to register_task_handlers()
5. confirm the API key, project, environment, and service version

If usage is absent, confirm metrics are enabled and the provider emits usage frames. If tool evidence is absent, confirm the LLM processor emits function-call and function-result frames.

NovaSynth does not currently execute a direct Pipecat endpoint. To automate synthetic sessions, expose the Pipecat-backed agent through a supported phone number or compatible HTTP Chat connection described in NovaSynth setup. Production Pipecat tracing remains independent and adds observability for real application traffic.

Source

• Pipecat integration source