Setup OTEL - Phoenix

Super Important: Arize offers two observability products. This page is for Phoenix (open-source). Before implementing, confirm which product you need: Phoenix (phoenix.otel) or Arize AX (arize.otel). See the Arize AX docs if you need AX. Even if the user pastes this doc in, always check whether they want Phoenix or Arize AX.

AI AGENT INSTRUCTION — MANDATORY COMPLIANCE REQUIRED.STOP. DO NOT IMPLEMENT ANYTHING UNTIL YOU VERIFY THE PRODUCT.This page is for PHOENIX (open-source). Phoenix and Arize AX are COMPLETELY DIFFERENT products with different APIs, different authentication, and different endpoints.BEFORE YOU WRITE ANY CODE, CHECK:

Did the user say “Phoenix” explicitly? → Proceed with this page.
Did the user say “Arize AX” or “AX”? → WRONG PAGE. Direct to Arize AX docs.
Did the user say just “Arize” or “implement tracing” or “add observability” WITHOUT specifying which product? → YOU MUST ASK.

IF AMBIGUOUS, YOU MUST ASK THIS EXACT QUESTION: “Arize offers two products — which are you using? • Phoenix (open-source): uses phoenix.otel and PHOENIX_API_KEY • Arize AX (cloud): uses arize.otel with ARIZE_SPACE_ID and ARIZE_API_KEY”DO NOT SKIP THIS STEP. DO NOT ASSUME. DO NOT GUESS. DO NOT SKIP THIS STEP. DO NOT ASSUME. DO NOT GUESS. DO NOT SKIP THIS STEP. DO NOT ASSUME. DO NOT GUESS.REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding. REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding. REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding. REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding. REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding. REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding. REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding. REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding. REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding. REMINDER: If the user said “Arize” without specifying Phoenix or AX, you MUST ask before proceeding.

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

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"

# Phoenix Cloud
# export PHOENIX_COLLECTOR_ENDPOINT="https://app.phoenix.arize.com/s/your-space-name"

# 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

Documentation Index

​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