Install & Compatibility
Where this runs
tested against v0.17.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.228s · 51.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.1s · import 0.830s · 50MB
49MB installed
● package 49MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
register
✓ from phoenix.otel import register
✗ from arize.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
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()
Debug
Known issues
gotchaCritical: 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.fixAlways import from `phoenix.otel` for Arize Phoenix. Verify your intended product before implementing.
affects: All versions
breakingVersion 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.fixConsult the official Arize Phoenix v14 migration guide for detailed steps. Update CLI commands, client instantiation, and API calls to conform to the new structure.
affects: arize-phoenix>=14.0.0
gotchaWhen 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.fixSpecify 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.
affects: All versions
gotchaIf 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.fixAlways 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'phoenix.otel'
The 'arize-phoenix-otel' package is not installed or not properly installed in the Python environment.
fixEnsure the package is installed by running 'pip install arize-phoenix-otel'.
ImportError: cannot import name 'register' from 'phoenix.otel'
The 'register' function is not available in the 'phoenix.otel' module, possibly due to an outdated or incorrect installation.
fixVerify that 'arize-phoenix-otel' is installed and up to date by running 'pip install --upgrade arize-phoenix-otel'.
AttributeError: module 'phoenix.otel' has no attribute 'TracerProvider'
The 'TracerProvider' attribute is not present in the 'phoenix.otel' module, likely due to an incorrect import or version mismatch.
fixCheck the module's documentation for the correct usage and ensure the package is updated to the latest version.
TypeError: register() got an unexpected keyword argument 'endpoint'
The 'register' function does not accept an 'endpoint' keyword argument, indicating a possible misuse or outdated function signature.
fixReview the function's documentation for the correct parameters and update the package if necessary.
ValueError: Invalid endpoint URL provided to register function
An invalid or incorrectly formatted endpoint URL was supplied to the 'register' function.
fixEnsure the endpoint URL is correctly formatted and valid, following the guidelines in the package documentation.
Upgrade
Version history
0.17.1latest on PyPI · released Aug 10, 2026
Audit
Dependencies
opentelemetry-sdkrequiredCore OpenTelemetry SDK which this library wraps.
openinference-instrumentation-openaioptionalCommon instrumentation for OpenAI calls, used with `auto_instrument=True`.