Environment:Arize ai Phoenix OpenTelemetry SDK
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Observability |
| Last Updated | 2026-02-14 06:00 GMT |
Overview
OpenTelemetry SDK environment with OTLP exporters and OpenInference semantic conventions for LLM tracing.
Description
This environment provides the OpenTelemetry instrumentation stack required for trace ingestion. It includes the OTel SDK for creating and managing TracerProviders, OTLP exporters for transmitting spans over HTTP and gRPC, and OpenInference semantic conventions that define the attribute schema for LLM observability spans.
The container (production) extra pins all OTel packages to coordinated versions (e.g., SDK 1.39.1, contrib 0.60b1) to ensure compatibility. When updating OTel dependencies, all packages must use versions released on the same date.
Usage
Use this environment for the Trace Ingestion Pipeline workflow: registering tracers, instrumenting applications, and transmitting spans to a Phoenix collector. It is required by all OTel-related implementations.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Python | >= 3.8 | phoenix-otel supports Python 3.8+ |
| Network | HTTP (4318) or gRPC (4317) | Standard OTLP ports |
Dependencies
Core OTel Packages
- `opentelemetry-sdk` (any version for basic use; ==1.39.1 for container)
- `opentelemetry-proto` >= 1.12.0 (avoids issue #2695)
- `opentelemetry-exporter-otlp`
- `opentelemetry-semantic-conventions`
OpenInference Packages
- `openinference-semantic-conventions` >= 0.1.26
- `openinference-instrumentation` >= 0.1.44
- `openinference-instrumentation-openai` >= 0.1.41
Container/Production Pinned Versions
- `opentelemetry-sdk` == 1.39.1
- `opentelemetry-proto` == 1.39.1
- `opentelemetry-exporter-otlp` == 1.39.1
- `opentelemetry-semantic-conventions` == 0.60b1
- `opentelemetry-instrumentation-fastapi` == 0.60b1
- `opentelemetry-instrumentation-sqlalchemy` == 0.60b1
- `opentelemetry-instrumentation-grpc` == 0.60b1
Credentials
The following environment variables configure the OTel collector connection:
- `PHOENIX_COLLECTOR_ENDPOINT`: Phoenix collector URL (takes precedence)
- `OTEL_EXPORTER_OTLP_ENDPOINT`: Standard OTel OTLP endpoint (fallback)
- `PHOENIX_CLIENT_HEADERS`: HTTP headers in W3C Baggage format
- `PHOENIX_API_KEY`: Bearer token for authenticated collectors
- `PHOENIX_PROJECT_NAME`: Target project name (defaults to "default")
- `PHOENIX_GRPC_PORT`: gRPC port (defaults to 4317)
Quick Install
# Install the OTel wrapper package
pip install arize-phoenix-otel
# Install with auto-instrumentation for OpenAI
pip install arize-phoenix-otel openinference-instrumentation-openai
Code Evidence
OTel proto version constraint from `pyproject.toml:46`:
"opentelemetry-proto>=1.12.0", # needed to avoid this issue: https://github.com/Arize-ai/phoenix/issues/2695
Container version pinning note from `pyproject.toml:194-196`:
# Note: when updating opentelemetry dependencies, all packages must use versions
# released on the same date (e.g., 1.39.1/0.60b1) to ensure compatibility.
"opentelemetry-sdk==1.39.1",
Collector endpoint resolution from `packages/phoenix-otel/src/phoenix/otel/settings.py:24-34`:
def get_env_collector_endpoint() -> Optional[str]:
return os.getenv(ENV_PHOENIX_COLLECTOR_ENDPOINT) or os.getenv(ENV_OTEL_EXPORTER_OTLP_ENDPOINT)
gRPC default port from `packages/phoenix-otel/src/phoenix/otel/settings.py:18-21`:
GRPC_PORT = 4317
"""The port the gRPC server will run on after launch_app is called.
The default network port for OTLP/gRPC is 4317."""
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `opentelemetry-proto version conflict` | Mismatched OTel package versions | Pin all OTel packages to same release date |
| `Header format invalid!` | Non-URL-encoded header values in env vars | URL-encode header values in PHOENIX_CLIENT_HEADERS |
| `Invalid value for PHOENIX_GRPC_PORT` | Non-numeric port string | Set PHOENIX_GRPC_PORT to a valid integer |
Compatibility Notes
- Version Coordination: All OpenTelemetry packages in the container extra must use versions from the same release date. Mixing versions causes runtime errors.
- Header Encoding: Client headers set via `PHOENIX_CLIENT_HEADERS` must be URL-encoded per the W3C Baggage HTTP header format. The system will attempt to URL-encode unencoded values but logs a warning.