arize-phoenix-otel

Provides a lightweight wrapper around OpenTelemetry primitives with Phoenix-aware defaults. Phoenix OTEL also gives you access to tracing decorators for common GenAI patterns.

Features

arize-phoenix-otel simplifies OpenTelemetry configuration for Phoenix users by providing:

• Phoenix-aware defaults for common OpenTelemetry primitives
• Automatic configuration from environment variables
• Drop-in replacements for OTel classes with enhanced functionality
• Simplified tracing setup with the register() function
• Tracing decorators for GenAI patterns

Key Benefits

• Zero Code Changes: Enable auto_instrument=True to automatically instrument AI libraries
• Production Ready: Built-in batching and authentication
• Phoenix Integration: Seamless integration with Phoenix Cloud and self-hosted instances
• OpenTelemetry Compatible: Works with existing OpenTelemetry infrastructure
• Server Version Independent: Versioned separately from the Phoenix server — any recent arize-phoenix-otel works with any Phoenix server version, with no version pairing to track (traces are sent over OTLP using OpenInference semantic conventions, both backward compatible)

These defaults are aware of environment variables you may have set to configure Phoenix:

• PHOENIX_COLLECTOR_ENDPOINT
• PHOENIX_PROJECT_NAME
• PHOENIX_CLIENT_HEADERS
• PHOENIX_API_KEY
• PHOENIX_GRPC_PORT

Installation

Install via pip:

pip install arize-phoenix-otel

Quick Start

Recommended: Enable automatic instrumentation to trace your AI libraries with zero code changes:

from phoenix.otel import register

# Recommended: Automatic instrumentation + production settings
tracer_provider = register(
    auto_instrument=True,  # Auto-trace OpenAI, LangChain, LlamaIndex, etc.
    batch=True,  # Production-ready batching
    project_name="my-app",  # Organize your traces
)

That's it! All openinference-* AI libraries are now automatically traced and sent to Phoenix.

Note: auto_instrument=True only works if the corresponding OpenInference instrumentation libraries are installed. For example, to automatically trace OpenAI calls, you need openinference-instrumentation-openai installed:

pip install openinference-instrumentation-openai
pip install openinference-instrumentation-langchain  # For LangChain
pip install openinference-instrumentation-llama-index  # For LlamaIndex

See the OpenInference repository for the complete list of available instrumentation packages.

Authentication

export PHOENIX_API_KEY="your-api-key"

# Or pass directly to register()
tracer_provider = register(api_key="your-api-key")

Endpoint Configuration

Configure where to send your traces:

Environment Variables (Recommended):

export PHOENIX_COLLECTOR_ENDPOINT="https://your-phoenix-instance.com"
export PHOENIX_PROJECT_NAME="my-project"

register() picks the transport from the endpoint. A URL with no path, like the one above, uses gRPC to the same host on port 4317 (PHOENIX_GRPC_PORT). A URL with a path, or a Phoenix Cloud URL, uses HTTP. If the gRPC port is not reachable, for example behind a reverse proxy or an ingress, pass protocol="http/protobuf".

Direct Configuration:

# A URL with a path uses HTTP, sent to the URL as given
tracer_provider = register(endpoint="http://localhost:6006/v1/traces")

# A URL with no path uses gRPC, sent to host:port as given
tracer_provider = register(endpoint="http://localhost:4317")

# Pass protocol to choose the transport yourself
tracer_provider = register(protocol="http/protobuf")

Usage Examples

Simple Setup

from phoenix.otel import register

# Basic setup - sends to localhost
tracer_provider = register(auto_instrument=True)

Production Configuration

tracer_provider = register(
    project_name="my-production-app",
    auto_instrument=True,  # Auto-trace AI/ML libraries
    batch=True,  # Background batching for performance
    api_key="your-api-key",  # Authentication
    endpoint="https://your-phoenix-instance.com/v1/traces",
)

Manual Configuration

For advanced use cases, use Phoenix OTEL components directly:

from phoenix.otel import TracerProvider, BatchSpanProcessor, HTTPSpanExporter

tracer_provider = TracerProvider()
exporter = HTTPSpanExporter(endpoint="http://localhost:6006/v1/traces")
processor = BatchSpanProcessor(span_exporter=exporter)
tracer_provider.add_span_processor(processor)

Using Decorators

from phoenix.otel import register

tracer_provider = register()

# Get a tracer for manual instrumentation
tracer = tracer_provider.get_tracer(__name__)


@tracer.chain
def process_data(data):
    return data + " processed"


@tracer.tool
def weather(location):
    return "sunny"

Environment Variables

Credential File Discovery (.env.phoenix)

When a setting is not provided by argument or environment variable, register() looks for a .env.phoenix file in the current working directory — walking up toward the filesystem root and stopping at the first match — and reads PHOENIX_-prefixed keys from it (dotenv format):

# .env.phoenix
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
PHOENIX_API_KEY=your-api-key

Explicit arguments and environment variables always take precedence — the file never overrides anything already set. Set PHOENIX_DISCOVER_CONFIG=false to disable discovery entirely.

Credentials (PHOENIX_API_KEY, PHOENIX_CLIENT_HEADERS, and OTEL_EXPORTER_OTLP_HEADERS) and server location (PHOENIX_COLLECTOR_ENDPOINT, OTEL_EXPORTER_OTLP_ENDPOINT, and PHOENIX_GRPC_PORT) are each resolved as a group from one source tier. This prevents a file-only gRPC port from rewriting a process-provided endpoint. If explicit or process credentials are paired with an endpoint from .env.phoenix, Phoenix OTel warns once and continues without logging credential values.

Discovery results, including a missing file, are cached per working directory for the process lifetime. Long-running processes can call phoenix.otel.settings.clear_env_file_cache() after creating or changing the file.

Coding Agent Skill

The Phoenix repo includes a phoenix-tracing skill that teaches coding agents (Claude Code, Cursor, etc.) how to instrument LLM applications with OpenInference tracing. Install it with:

npx skills add Arize-ai/phoenix --skill phoenix-tracing

Documentation

• Full Documentation - Complete API reference and guides
• Phoenix Docs - Detailed tracing examples and patterns
• OpenInference - Auto-instrumentation libraries for frameworks

Community

Join our community to connect with thousands of AI builders:

• 🌍 Join our Slack community.
• 💡 Ask questions and provide feedback in the #phoenix-support channel.
• 🌟 Leave a star on our GitHub.
• 🐞 Report bugs with GitHub Issues.
• 𝕏 Follow us on 𝕏.
• 💼 Follow us on LinkedIn.
• 🗺️ Check out our roadmap to see where we're heading next.