Arize Phoenix OpenTelemetry Wrapper

0.15.0 · active · verified Sat Apr 11

arize-phoenix-otel is a Python library that provides a lightweight wrapper around OpenTelemetry primitives, offering Phoenix-aware defaults and tracing decorators for common Generative AI patterns. It simplifies the setup of OpenTelemetry for sending traces to Arize Phoenix, an open-source AI observability platform. The library is actively maintained, with frequent updates released as part of the larger `arize-phoenix` monorepo, currently at version 0.15.0.

Warnings

gotcha Critical: There are two distinct Arize products with separate Python packages: `arize-phoenix-otel` (for open-source Phoenix) and `arize-otel` (for Arize AX, a cloud product). Ensure you are using `from phoenix.otel import register` for Arize Phoenix. Using `arize.otel` will configure tracing for the wrong product.
Fix: Always import from `phoenix.otel` for Arize Phoenix. Verify your intended product before implementing.
breaking Version 14.0.0 of the broader `arize-phoenix` ecosystem (which `arize-phoenix-otel` is part of) introduced several breaking changes. These include the removal of the `/v1/evaluations` endpoint, deprecation and removal of Evals 1.0 modules, and significant changes to the CLI and the `arize-phoenix-client` package (e.g., `px.Client()` removed, `endpoint` parameter renamed to `base_url`). While `arize-phoenix-otel` focuses on tracing, these changes can affect how users interact with the Phoenix backend.
Fix: Consult the official Arize Phoenix v14 migration guide for detailed steps. Update CLI commands, client instantiation, and API calls to conform to the new structure.
gotcha When configuring the OpenTelemetry collector endpoint directly, you must provide a fully qualified URL including the path. For HTTP/protobuf, this is typically `http://localhost:6006/v1/traces`, and for gRPC, it's `http://localhost:4317`. Simply providing `http://localhost:6006` or `http://localhost` may lead to incorrect endpoint resolution.
Fix: Specify the complete endpoint URL (e.g., `register(endpoint="http://my-phoenix.com:6006/v1/traces")`) or ensure `PHOENIX_COLLECTOR_ENDPOINT` environment variable is set with the full URL.
gotcha If batch processing of spans is enabled (`batch=True` in `register()`), it's crucial to call `tracer_provider.shutdown()` before your application process exits. Failing to do so may result in queued spans not being exported to the Phoenix collector, leading to incomplete traces.
Fix: Always call `tracer_provider.shutdown()` at the end of your application's lifecycle, especially in short-lived scripts. Alternatively, use `batch=False` for immediate (but potentially less efficient) export or use `with register(...) as tracer_provider:` context manager.

Install

pip install arize-phoenix-otel Install latest version

Imports

register
```
from phoenix.otel import register
```
The `arize.otel` package is for Arize AX (a different cloud product), while `phoenix.otel` is for the open-source Arize Phoenix. Using the wrong import will lead to incorrect setup and data routing.
TracerProvider
```
from phoenix.otel import TracerProvider
```

HTTPSpanExporter

from phoenix.otel import HTTPSpanExporter

Quickstart

This quickstart demonstrates how to initialize the OpenTelemetry tracer with Arize Phoenix using the `register()` function. It shows how to configure a project name, enable automatic instrumentation for common AI/ML libraries, and includes a manual span creation. Crucially, it highlights the need for `tracer_provider.shutdown()` when using batch processing to ensure all telemetry data is exported before the application terminates. Environment variables (`PHOENIX_COLLECTOR_ENDPOINT`, `PHOENIX_API_KEY`, `PHOENIX_PROJECT_NAME`) are automatically read for configuration.

import os
from phoenix.otel import register
from opentelemetry import trace

# Configure Phoenix collector endpoint and API key via environment variables
# PHOENIX_COLLECTOR_ENDPOINT defaults to http://localhost:4317 (gRPC) or http://localhost:6006/v1/traces (HTTP)
# PHOENIX_API_KEY for authentication if required by your Phoenix instance

# Example usage with explicit project name and auto-instrumentation
# For production, set PHOENIX_COLLECTOR_ENDPOINT and PHOENIX_API_KEY environment variables.
# If running locally without env vars, it defaults to localhost.
tracer_provider = register(
    project_name=os.environ.get('PHOENIX_PROJECT_NAME', 'my-llm-app'),
    auto_instrument=True, # Automatically instruments supported AI/ML libraries like OpenAI, LangChain
    batch=True # Enable batch processing for better performance, requires shutdown call
)

# Get a tracer
tracer = trace.get_tracer(__name__)

# Example of creating a span manually (if auto_instrument=False or for custom logic)
with tracer.start_as_current_span("my-manual-operation") as span:
    span.set_attribute("input", "test data")
    print("Performing a traced operation...")
    span.set_attribute("output", "result data")

# Important: If batch=True, ensure all spans are flushed before the process exits
tracer_provider.shutdown()

view raw JSON →