The Phoenix OTEL SDK provides a lightweight wrapper around OpenTelemetry with sensible defaults for Phoenix.
Go users: Phoenix does not ship a branded phoenix-otel SDK wrapper for Go. Configure the standard OpenTelemetry Go SDK directly and point an OTLP/HTTP exporter at Phoenix. End-to-end examples live in the Go integration pages — OpenAI Go SDK, Anthropic SDK Go, and Gemini Go SDK.
Let your coding agent set this up. Works with Claude Code, Codex, Cursor, and OpenCode.
Start Phoenix
In one terminal, start Phoenix and leave it running. It serves at http://localhost:6006:
Already have a Phoenix deployment? Skip this step. px setup can point at any running Phoenix, including a self-hosted one.
Add tracing with a coding agent
In a new terminal, from your app’s root directory, run one of these:
px setup hands the instrumentation to your coding agent and waits until a real trace arrives. It can also install the Phoenix skills so your agent can query what you capture. See Connect a project with px setup for the full flow, CI usage, and unsupported agents.
Install#
Version 0.16.0 or later is required to import OpenInference context managers and semantic conventions directly from phoenix.otel. On earlier versions, import them from openinference.instrumentation and openinference.semconv.trace instead.
Do I need to match the SDK version to my Phoenix server version? No. arize-phoenix-otel (and @arizeai/phoenix-otel) are versioned independently of the Phoenix server. Any recent SDK version works with any Phoenix server version — you don’t need to upgrade the server when you upgrade the SDK, or vice versa. The SDK sends traces over OTLP using OpenInference semantic conventions, both of which are backward compatible, so there is no version pairing to track. See The phoenix.otel helpers for why.
Configure#
Set environment variables to connect to your Phoenix instance:
You can find your collector endpoint and API key in the Settings page of your Phoenix instance.
Register#
Call register() to initialize tracing. The SDK automatically reads your environment variables.
For manual instrumentation, arize-phoenix-otel (>=0.16.0) and @arizeai/phoenix-otel re-export all commonly used OpenInference helpers so a single dependency is sufficient:
- Python: context managers (
using_session,using_user,using_metadata,using_tags,using_attributes,using_prompt_template,suppress_tracing) and semantic conventions (SpanAttributes,OpenInferenceSpanKindValues,OpenInferenceMimeTypeValues). - TypeScript:
withSpan,traceChain,traceAgent,traceTool,observe, and context setters likesetSessionandsetMetadata.
Configuration options
| Parameter | Description |
|---|---|
project_name | Project name in Phoenix (or PHOENIX_PROJECT_NAME env var) |
auto_instrument | Automatically instrument all supported libraries |
batch | Process spans in batch (default: False) |
endpoint | Custom collector endpoint URL |
protocol | Transport protocol: "grpc" or "http/protobuf" |
headers | Headers to send with each span payload |
Configuration options
| Parameter | Type | Default | Description |
|---|---|---|---|
projectName | string | "default" | Project name in Phoenix |
url | string | "http://localhost:6006" | Phoenix server URL |
apiKey | string | — | API key for authentication |
batch | boolean | true | Use batch span processing |
headers | Record<string, string> | {} | Custom headers for OTLP requests |
instrumentations | Instrumentation[] | — | Instrumentations to register |
global | boolean | true | Register as the global tracer provider |
spanProcessors | SpanProcessor[] | — | Custom span processors (overrides default exporter) |
diagLogLevel | DiagLogLevel | — | Enable diagnostic logging |
Instrument#
Add instrumentation to capture traces from your LLM calls:
With auto_instrument=True, Phoenix automatically discovers and activates all OpenInference instrumentor packages installed in your Python environment—no additional code required.
Just pip install the instrumentation packages you need and set auto_instrument=True. Phoenix handles the rest.
See Integrations for all available packages, or use Tracing Helpers for manual instrumentation.
Install and register instrumentations for your framework:
ESM projects require calling manuallyInstrument() on the client class. CommonJS projects can skip this step.
For manual spans, import the helpers from @arizeai/phoenix-otel. Phoenix’s wrappers resolve the active global tracer when they execute, so the same traced function keeps working inside experiment runs and other provider swaps.
See Integrations for all available packages.
Spans may not be exported if still queued in the processor when your process exits. With batch: true, call shutdown() to explicitly flush before exit. Alternatively, use batch: false for immediate export.
Advanced Configuration#
For more control over tracing behavior, see the SDK reference documentation: