Principle:Arize ai Phoenix OTel Dependency Setup

Knowledge Sources	arize-phoenix-otel PyPI Phoenix
Domains	AI Observability, Dependency Management, OpenTelemetry
Last Updated	2026-02-14 00:00 GMT

Overview

Managing OpenTelemetry dependencies for AI observability requires a coordinated set of SDK libraries, exporters, and semantic convention packages that work together to produce, transmit, and interpret telemetry data from LLM applications.

Description

Modern AI applications built on large language models benefit from observability tooling that captures request and response payloads, token counts, latency breakdowns, and error states. The OpenTelemetry (OTel) standard provides a vendor-neutral framework for distributed tracing, but instrumenting LLM workloads requires additional semantic conventions and transport mechanisms beyond what the base OTel SDK provides.

The OTel Dependency Setup principle addresses the challenge of assembling the correct collection of packages needed to enable end-to-end trace capture for AI applications. This includes:

• OpenTelemetry SDK (opentelemetry-sdk): The core tracing SDK that provides TracerProvider, SpanProcessor, and Resource abstractions.
• OTLP Exporters (opentelemetry-exporter-otlp-proto-http, opentelemetry-exporter-otlp-proto-grpc): Transport-layer components responsible for serializing spans into the OTLP protobuf format and transmitting them over HTTP or gRPC.
• Semantic Conventions (openinference-semantic-conventions): A standardized vocabulary of attribute keys (e.g., llm.token_count.prompt, input.value, output.value) that give structure and meaning to LLM trace data.
• Instrumentation Framework (openinference-instrumentation): Base classes and entry point discovery mechanisms that allow individual LLM library instrumentors (e.g., for OpenAI, LangChain, LlamaIndex) to register themselves and be auto-discovered.

Without a coordinated dependency setup, users face version incompatibilities between the OTel SDK and the exporter protocols, missing semantic attributes that prevent the collector from correctly interpreting LLM spans, or missing instrumentation hooks that leave application calls untraced.

Usage

Use this principle whenever:

• Setting up a new Python project that requires LLM observability.
• Migrating an existing application from a proprietary tracing solution to an OpenTelemetry-based approach.
• Troubleshooting missing or malformed trace data that may result from version mismatches among OTel packages.
• Evaluating which transport protocol (HTTP vs. gRPC) to use based on infrastructure constraints.

Theoretical Basis

The dependency graph follows the layered architecture of OpenTelemetry:

Application Code
       |
       v
[Instrumentation Libraries]   <-- openinference-instrumentation + per-library instrumentors
       |
       v
[TracerProvider + SpanProcessor]   <-- opentelemetry-sdk
       |
       v
[SpanExporter (HTTP or gRPC)]   <-- opentelemetry-exporter-otlp-proto-http / grpc
       |
       v
[Collector / Phoenix Server]

Each layer depends on the one below it. The semantic conventions package (openinference-semantic-conventions) is a cross-cutting concern used by both the instrumentation layer (to set attributes) and the collector layer (to interpret attributes).

The key design constraint is version compatibility: the OTLP exporter must produce protobuf messages compatible with the collector's receiver, and the semantic convention keys used by instrumentors must match what the collector expects. Bundling these dependencies into a single meta-package ensures they are tested together and avoids "dependency hell" scenarios.

Environment Variables

While the dependency setup itself is a packaging concern, the installed packages respect several environment variables that influence runtime behavior:

Variable	Purpose
PHOENIX_COLLECTOR_ENDPOINT	Base URL for the Phoenix collector (default: http://localhost:6006)
PHOENIX_PROJECT_NAME	Project name attached as a resource attribute to all spans
PHOENIX_API_KEY	API key for authenticated collector endpoints
PHOENIX_CLIENT_HEADERS	Additional headers to include in export requests

Related Pages

Implemented By

• Implementation:Arize_ai_Phoenix_Pip_Install_Phoenix_Otel