Setup OTEL

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.

Install

Python
TypeScript

pip install "arize-phoenix-otel>=0.16.0"

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.

npm install @arizeai/phoenix-otel

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:

export PHOENIX_API_KEY="your-api-key"

# Local (default, no API key required)
export PHOENIX_COLLECTOR_ENDPOINT="http://localhost:6006"

# A remote Phoenix deployment
# export PHOENIX_COLLECTOR_ENDPOINT="https://your-phoenix.example.com"

# Self-hosted
# export PHOENIX_COLLECTOR_ENDPOINT="https://your-phoenix-instance.com"

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 like setSession and setMetadata.

Python
TypeScript

from phoenix.otel import register

tracer_provider = register(
    project_name="my-llm-app",
    auto_instrument=True,  # automatically instruments OpenAI, LangChain, etc.
)

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

import { register } from "@arizeai/phoenix-otel";

register({ projectName: "my-llm-app" });

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:

Python
TypeScript

With auto_instrument=True, Phoenix automatically discovers and activates all OpenInference instrumentor packages installed in your Python environment—no additional code required.

# Install instrumentors for your frameworks
pip install openinference-instrumentation-openai
pip install openinference-instrumentation-langchain
# ... any other OpenInference packages you need

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:

npm install @arizeai/openinference-instrumentation-openai

import OpenAI from "openai";
import { register, registerInstrumentations } from "@arizeai/phoenix-otel";
import { OpenAIInstrumentation } from "@arizeai/openinference-instrumentation-openai";

register({ projectName: "my-llm-app" });

const instrumentation = new OpenAIInstrumentation();
instrumentation.manuallyInstrument(OpenAI);

registerInstrumentations({
  instrumentations: [instrumentation],
});

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:

Python arize-phoenix-otel

Batch processing, custom endpoints, gRPC/HTTP transport, sampling, and OTel primitives

TypeScript @arizeai/phoenix-otel

Diagnostic logging, custom headers, and full API reference

Next Steps

Integrations

Browse auto-instrumentation packages

Tracing Helpers

Manual instrumentation with decorators

Get Started

Tracing

Evaluation

Datasets & Experiments

Prompts

Settings

Concepts

Resources

Install

Configure

Register

Instrument

Advanced Configuration

Python arize-phoenix-otel

TypeScript @arizeai/phoenix-otel

Next Steps

Integrations

Tracing Helpers

​Install

​Configure

​Register

​Instrument

​Advanced Configuration

Python arize-phoenix-otel

TypeScript @arizeai/phoenix-otel

​Next Steps

Integrations

Tracing Helpers

Install

Configure

Register

Instrument

Advanced Configuration

Next Steps