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.1. Installation
Install the traceAI Pipecat package:2. Set Environment Variables
Set up your environment variables to authenticate with FutureAGI and Pipecat:3. Initialize Trace Provider
Set up the trace provider to establish the observability pipeline:4. Enable Attribute Mapping
Enable attribute mapping to convert Pipecat attributes to Future AGI conventions. This method automatically updates your existing span exporters:5. Initialize The Pipecat Application
Initialize the Pipecat application with the trace provider:Enabling Tracing in Pipecat requires you to set the
enable_tracing
flag to True
in the PipelineParams
object.
refer to this link for more details.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
tollm.provider
,llm.model_name
- Input/Output: Maps
input
,output
,transcript
to structured Future AGI format - Token Usage: Maps
gen_ai.usage.*
tollm.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 appropriatefi.span.kind
based on span attributes:
LLM
: For LLM, STT, and TTS operationsTOOL
: For tool calls and resultsAGENT
: For setup and configuration spansCHAIN
: For turn and conversation spans
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
orTransport.GRPC
)
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
-
No exporters found to replace
- Ensure you’ve called
register()
before installing attribute mapping - Check that the transport type matches your tracer provider configuration
- Ensure you’ve called
-
Import errors for gRPC
- Install gRPC dependencies:
pip install "fi-instrumentation[grpc]"
- Install gRPC dependencies:
-
Data not being sent to FutureAGI
- Ensure that you have set the
FI_API_KEY
andFI_SECRET_KEY
environment variables - Ensure that the
set_global_tracer_provider
in theregister
function is set toTrue
- Ensure that you have set the