Trace a Pipecat voice pipeline

Add Future AGI tracing to an existing Pipecat voice bot to inspect conversation, turn, STT, LLM and TTS spans in Observe. Pipecat creates the spans; the maintained traceAI-pipecat package maps their attributes for Future AGI.

Before you start

Use a working Pipecat bot with its service credentials, transport and client already configured. If you need a bot first, follow the Pipecat quickstart. Keep the service and transport extras required by that application: the tracing extra alone does not install a WebRTC runner or your speech services.

The configuration below uses Pipecat 1.15.0 and traceAI-pipecat 0.1.1 with Python 3.11 to 3.13.

Install

pip install traceAI-pipecat==0.1.1 "pipecat-ai[tracing]==1.15.0"

For a SmallWebRTC bot using OpenAI, Deepgram, Cartesia and Silero, include its service and runner extras:

pip install "pipecat-ai[tracing,webrtc,runner,openai,deepgram,cartesia,silero]==1.15.0"

Set environment variables

export FI_API_KEY="your-futureagi-api-key"
export FI_SECRET_KEY="your-futureagi-secret-key"

For self-hosted Future AGI, also set FI_BASE_URL to your collector origin. Keep the provider keys used by your bot in its normal environment.

Register the provider and mapping

Run this once at application startup, before constructing the pipeline worker. Use this provider instead of separately calling Pipecat’s setup_tracing() or installing a second exporter.

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from fi_instrumentation.otel import Transport
from traceai_pipecat import enable_http_attribute_mapping

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="Pipecat Voice App",
    transport=Transport.HTTP,
    set_global_tracer_provider=True,
)

if not enable_http_attribute_mapping():
    raise RuntimeError("No Future AGI HTTP exporter found for Pipecat mapping")

The mapping function updates the existing Future AGI exporter. It returns False when it cannot find one; do not continue assuming that mapping is enabled.

Enable native tracing in your bot

In the code that constructs your existing pipeline worker, enable tracing and turn tracking. Here, pipeline is the pipeline your bot already builds; keep its transport handlers, observers and runner lifecycle.

from pipecat.pipeline.worker import PipelineParams, PipelineWorker

worker = PipelineWorker(
    pipeline,
    params=PipelineParams(
        enable_metrics=True,
        enable_usage_metrics=True,
    ),
    enable_tracing=True,
    enable_turn_tracking=True,
)

Pipecat generates a conversation ID when you omit conversation_id. If you supply an ID or additional_span_attributes, use non-sensitive values. The current Pipecat OpenTelemetry guide uses PipelineWorker; the older PipelineTask API is deprecated in Pipecat 1.15.0.

Start the bot with its existing launch command and connect using its normal voice client. For SmallWebRTC setup and client launch, follow the Pipecat quickstart rather than running an incomplete transport example.

After the bot’s runner has stopped and its conversation spans have ended, flush and shut down the provider once during application shutdown:

trace_provider.force_flush()
trace_provider.shutdown()

Do not shut down the provider after each conversation in a process serving multiple conversations.

Open the result

Open Observe and select Pipecat Voice App. Inspect the conversation and turn spans and the service spans your pipeline emits. Model, token and timing fields depend on the services and metrics they report; enabling mapping does not create measurements that Pipecat did not emit.

Troubleshooting

• No exporter found for mapping: call register() first with set_global_tracer_provider=True and HTTP transport. Do not replace the global provider afterward.
• No conversation or turn spans: install Pipecat’s tracing extra and enable tracing and turn tracking on the worker.
• Bot or WebRTC client will not start: confirm the bot works without tracing, and install its service, webrtc and runner extras as needed. Tracing setup does not configure the voice transport.
• Last spans are missing: let the runner finish before flushing. A forced process kill can lose buffered spans.
• Sensitive content appears in attributes: native Pipecat tracing includes content. Disable tracing if this is incompatible with your data policy; attribute mapping alone does not redact it.