Skip to main content

​
Overview

PipecatInstrumentor is an auto-instrumentation library that converts Pipecat traces to OpenInference, an OpenTelemetry-compatible tracing format. It automatically wraps your PipelineWorker to observe frame flow and create spans for LLM, TTS, and STT services, which you can then view in Arize Phoenix or Arize AX.

Source Repository

Source code, examples, and issues for the OpenInference Pipecat instrumentation

PyPI Package

The openinference-instrumentation-pipecat package on PyPI

OpenInference

OpenInference specification and documentation

Arize Phoenix

Open-source LLM observability platform for viewing traces

​
Installation

This is a community-maintained package distributed separately from pipecat-ai: 
pip install openinference-instrumentation-pipecat

​
Prerequisites

This instrumentation emits OpenTelemetry traces in the OpenInference format, so you need a backend to send them to. The repository’s quickstart uses Arize Phoenix (open source) or Arize AX:
  • Phoenix: Run Phoenix locally or use a hosted instance, then register a tracer provider with phoenix.otel.register(...).
  • Arize AX: Provide an ARIZE_SPACE_ID and ARIZE_API_KEY and register with arize.otel.register(...).
Because traces are standard OpenTelemetry, any OTLP-compatible backend may be used. See the source repository for the authoritative setup details.

​
Usage

Set up a tracer provider and enable the instrumentor at the top of your application, before building your Pipecat pipeline: 
from phoenix.otel import register
from openinference.instrumentation.pipecat import PipecatInstrumentor

# Set up the tracer provider
tracer_provider = register(
    project_name="default",  # Phoenix project name
)

# Add the auto-instrumentor at the top of the application
PipecatInstrumentor().instrument(tracer_provider=tracer_provider)

# Build your Pipecat pipeline as usual
pipeline = Pipeline(...)

worker = PipelineWorker(
    pipeline,
    conversation_id=conversation_id,  # used for session tracking in Arize or Phoenix
)

runner = PipelineRunner(handle_sigint=runner_args.handle_sigint)
await runner.run(worker)
Once instrumented, the library injects an observer into each PipelineWorker, and exchanges in the running application are logged to your project in Phoenix or Arize AX.
The instrumentor wraps PipelineWorker. The deprecated PipelineTask alias is a thin subclass of PipelineWorker and is covered transparently. See the source repository for the full example.

​
Compatibility

The instrumentation tracks Pipecat versions as follows:
openinference-instrumentation-pipecatpipecat-aiPython
>=2.0>=1.3>=3.11
>=1.0, <2.0>=1.0, <1.3>=3.11
<=0.1.4<1.0 (e.g. 0.0.99)>=3.10
Pipecat 1.3 deprecated PipelineTask in favor of PipelineWorker; use >=2.0 with pipecat-ai>=1.3. Check the source repository for the latest tested versions and changelog.