Skip to main content

Pipecat OpenTelemetry Integration

Overview

This integration provides support for using OpenTelemetry with Pipecat applications. It enables tracing and monitoring of voice applications built with Pipecat, with automatic attribute mapping to Future AGI conventions.

Installation

  1. Install traceAI Pipecat
pip install traceAI-pipecat

Set Environment Variables

Set up your environment variables to authenticate with FutureAGI and Pipecat.

import os

os.environ["FI_API_KEY"] = FI_API_KEY
os.environ["FI_SECRET_KEY"] = FI_SECRET_KEY

Quickstart

This method automatically updates your existing span exporters to include Pipecat attribute mapping.

Register Tracer Provider

Set up the trace provider to establish the observability pipeline:

from fi_instrumentation.otel import register, Transport, ProjectType

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

Install Attribute Mapping

Install attribute mapping to convert Pipecat attributes to Future AGI conventions:

from traceai_pipecat import enable_http_attribute_mapping

# For HTTP transport
success = enable_http_attribute_mapping()

# For gRPC transport
from traceai_pipecat import enable_grpc_attribute_mapping
success = enable_grpc_attribute_mapping()

# Or specify transport explicitly via enum
from traceai_pipecat import enable_fi_attribute_mapping
from fi_instrumentation.otel import Transport
success = enable_fi_attribute_mapping(transport=Transport.HTTP)  # or Transport.GRPC

Features

Automatic Attribute Mapping

The integration automatically maps Pipecat-specific attributes to Future AGI conventions:

  • LLM Operations: Maps gen_ai.system, gen_ai.request.model to llm.provider, llm.model_name
  • Input/Output: Maps input, output, transcript to structured Future AGI format
  • Token Usage: Maps gen_ai.usage.* to llm.token_count.*
  • Tools: Maps tool-related attributes to Future AGI tool conventions
  • Session Data: Maps conversation and session information
  • Metadata: Consolidates miscellaneous attributes into structured metadata

Transport Support

  • HTTP: Full support for HTTP transport with automatic endpoint detection
  • gRPC: Support for gRPC transport (requires fi-instrumentation[grpc])

Span Kind Detection

Automatically determines the appropriate fi.span.kind based on span attributes:

  • LLM: For LLM, STT, and TTS operations
  • TOOL: For tool calls and results
  • AGENT: For setup and configuration spans
  • CHAIN: For turn and conversation spans

Examples

Complete HTTP Integration Example

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

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

# Install attribute mapping
try:
    enable_http_attribute_mapping()
    print("✅ Successfully installed HTTP attribute mapping")
except Exception as e:
    print(f"❌ Error: {e}")

# Your Pipecat application code here...

Complete gRPC Integration Example

from fi_instrumentation.otel import register, Transport, ProjectType
from traceai_pipecat import enable_grpc_attribute_mapping

# Initialize tracer provider
trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="My Pipecat Voice App",
    transport=Transport.GRPC,
    set_global_tracer_provider=True,
)

# Install attribute mapping
try:
    enable_grpc_attribute_mapping()
    print("✅ Successfully installed gRPC attribute mapping")
except Exception as e:
    print(f"❌ Error: {e}")

# Your Pipecat application code here...

API Reference

Integration Functions

enable_fi_attribute_mapping(transport: Transport = Transport.HTTP) -> bool

Install attribute mapping by replacing existing span exporters.

Parameters:

  • transport: Transport protocol enum (Transport.HTTP or Transport.GRPC)

Returns:

  • bool: True if at least one exporter was replaced

enable_http_attribute_mapping() -> bool

Convenience function for HTTP transport.

enable_grpc_attribute_mapping() -> bool

Convenience function for gRPC transport.

Exporter Creation Functions

create_mapped_http_exporter(endpoint: Optional[str] = None, headers: Optional[dict] = None)

Create a new HTTP exporter with Pipecat attribute mapping.

create_mapped_grpc_exporter(endpoint: Optional[str] = None, headers: Optional[dict] = None)

Create a new gRPC exporter with Pipecat attribute mapping.

Exporter Classes

MappedHTTPSpanExporter

HTTP span exporter that maps Pipecat attributes to Future AGI conventions.

MappedGRPCSpanExporter

gRPC span exporter that maps Pipecat attributes to Future AGI conventions.

BaseMappedSpanExporter

Base class for mapped span exporters.

Troubleshooting

Common Issues

  1. No exporters found to replace

    • Ensure you've called register() before installing attribute mapping
    • Check that the transport type matches your tracer provider configuration
  2. Import errors for gRPC

    • Install gRPC dependencies: pip install "fi-instrumentation[grpc]"
  3. Data not being sent to FutureAGI

    • Ensure that your you have set the FI_API_KEY and FI_SECRET_KEY environment variables
    • Ensure that the set_global_tracer_provider in the register function is set to True

Metadata

Release files for traceAI-pipecat 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for traceAI-pipecat 0.1.3
File Size Uploaded Provenance Actions
traceai_pipecat-0.1.3.tar.gz 8.5 kB With provenance Details for traceai_pipecat-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for traceAI-pipecat 0.1.3
File Interpreter ABI Platform Actions
traceai_pipecat-0.1.3-py3-none-any.whl Python 3 none any Details for traceai_pipecat-0.1.3-py3-none-any.whl

Total release size: 18.5 kB

Release files / traceai_pipecat-0.1.3.tar.gz

Download URL traceai_pipecat-0.1.3.tar.gz
Size 8.5 kB
Tags Source
SHA-256 checksum
How to use checksums
fb462015e2e78f08a962dda9670b63d2d0e3428458b52bd1b85c52fe0537e7f0
BLAKE2b-256 checksum
How to use checksums
b21de57d12188b593f7951609964f4eca8528f34d8363f42a65892c69d2825d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / traceai_pipecat-0.1.3-py3-none-any.whl

Download URL traceai_pipecat-0.1.3-py3-none-any.whl
Size 10.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
83ce546e6eab76e1e93357ee22ba1bba4b1f3168e24148ee7f2a917a1bea0026
BLAKE2b-256 checksum
How to use checksums
0d995b6bd1d31d6f0ef7a114cc78e75c0cf745aeae018b115d1caf89cfff911b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for traceAI-pipecat 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for traceai_pipecat-0.1.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page