Overview - Phoenix

@arizeai/phoenix-otel is the Phoenix-focused OpenTelemetry package for Node.js. It handles provider setup, OTLP export, and instrumentation registration, then re-exports the full @arizeai/openinference-core helper surface and OpenInference semantic conventions from the same package path.

Install#

Install the package and any OpenTelemetry instrumentations you want to use with it.

npm install @arizeai/phoenix-otel

Add Instrumentations#

npm install \  @arizeai/phoenix-otel \  @opentelemetry/instrumentation-http \  @opentelemetry/instrumentation-express

What This Package Includes#

@arizeai/phoenix-otel combines Phoenix registration with OpenInference authoring APIs:

Phoenix registration: register(), attachGlobalTracerProvider(), detachGlobalTracerProvider(), createNoOpProvider()
OpenInference wrappers: withSpan(), traceChain(), traceAgent(), traceTool(), traceLLM(), traceRetriever(), traceReranker(), traceEmbedding(), traceGuardrail(), traceEvaluator(), tracePrompt()
decorators and context propagation: observe(), setSession(), setUser(), setMetadata(), setTags(), setPromptTemplate(), setAttributes()
attribute builders: getLLMAttributes(), getRetrieverAttributes(), getEmbeddingAttributes(), getToolAttributes(), getMetadataAttributes(), getInputAttributes(), getOutputAttributes(), defaultProcessInput(), defaultProcessOutput()
redaction and safety helpers: OITracer, withSafety, safelyJSONStringify, safelyJSONParse
OpenTelemetry utilities: trace, context, SpanStatusCode, DiagLogLevel, registerInstrumentations()

The re-exported OpenInference wrappers resolve the default tracer when the wrapped function runs, so module-scoped traced helpers continue following global provider changes.

Quick Start#

import { register, traceChain } from "@arizeai/phoenix-otel";const provider = register({ projectName: "support-bot" });const handleQuery = traceChain(  async (query: string) => {    return `Handled: ${query}`;  },  { name: "handle-query" });await handleQuery("Hello");await provider.shutdown();

If you want raw control over span shape, switch to withSpan() or the OpenTelemetry trace API. The package docs linked below cover both patterns.

Docs And Source In `node_modules`#

After install, a coding agent can inspect the installed package directly:

node_modules/@arizeai/phoenix-otel/docs/node_modules/@arizeai/phoenix-otel/src/

Because @arizeai/phoenix-otel re-exports @arizeai/openinference-core, the dependency docs are also high-value local references:

node_modules/@arizeai/openinference-core/docs/node_modules/@arizeai/openinference-core/src/

Configuration#

register() can use explicit options, environment variables, or both. If you pass a Phoenix base URL, the package normalizes it to the OTLP collector endpoint at /v1/traces.

Environment-Driven Setup#

export PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006export PHOENIX_API_KEY=<your-api-key>

import { register } from "@arizeai/phoenix-otel";const provider = register({  projectName: "support-bot",});

Explicit Setup#

import { DiagLogLevel, register } from "@arizeai/phoenix-otel";const provider = register({  projectName: "support-bot",  url: "https://your-phoenix.example.com",  apiKey: process.env.PHOENIX_API_KEY,  headers: {    "x-client-name": "support-bot-api",    "x-client-version": "1.4.2",  },  batch: true,  diagLogLevel: DiagLogLevel.INFO,});

Key Options#

Option	Description
`projectName`	Phoenix project name attached to exported spans. Defaults to `default`.
`url`	Phoenix base URL or full collector endpoint. The package appends `/v1/traces` when needed.
`apiKey`	API key sent as a bearer token. Falls back to `PHOENIX_API_KEY`.
`headers`	Additional OTLP headers merged with the auth header.
`batch`	`true` for batched export, `false` for immediate export during debugging.
`instrumentations`	OpenTelemetry instrumentations to register with the provider.
`spanProcessors`	Custom span processors. When provided, these replace the default Phoenix exporter setup.
`global`	Whether to attach the provider to the global OpenTelemetry APIs automatically.
`diagLogLevel`	OpenTelemetry diagnostic logging level.

Environment Variables#

Variable	Use
`PHOENIX_COLLECTOR_ENDPOINT`	Base Phoenix collector URL or full OTLP trace endpoint.
`PHOENIX_API_KEY`	API key used when you do not pass `apiKey` explicitly.

Instrumentation#

Vercel AI SDK (v7+)#

AI SDK v7 telemetry registration is process-global, so configure it explicitly in your application. Install ai and @ai-sdk/otel; the bundled @arizeai/openinference-vercel span processors then translate the emitted spans to OpenInference before export.

import { OpenTelemetry } from "@ai-sdk/otel";import { registerTelemetry } from "ai";import { register } from "@arizeai/phoenix-otel";const provider = register({ projectName: "my-ai-app" });registerTelemetry(  new OpenTelemetry({    tracer: provider.getTracer("@arizeai/phoenix-otel/ai-sdk"),    // Headers can contain authorization tokens and cookies.    headers: false,  }));

call registerTelemetry() only once during application startup
compose this integration with any logging, metrics, or custom integrations your application already registers
AI SDK v6 and older emit a different span shape; use @arizeai/phoenix-otel 1.x for AI SDK v6

OpenTelemetry Instrumentations#

Pass OpenTelemetry instrumentations to register() to capture framework and library activity automatically.

import { register } from "@arizeai/phoenix-otel";import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";register({  projectName: "support-bot",  instrumentations: [    new HttpInstrumentation(),    new ExpressInstrumentation(),  ],});

registerInstrumentations() is also re-exported for manual setups
auto-instrumentation works best when initialized very early in process startup
ESM projects often need manual library instrumentation rather than loader-based auto-instrumentation

Production#

Enable Batch Processing#

Keep batch: true in production. The batch span processor groups spans before export, reducing request volume and export overhead. Disable batching only when you need immediate local feedback.

const provider = register({  projectName: "support-bot",  url: "https://your-phoenix.example.com",  apiKey: process.env.PHOENIX_API_KEY,  batch: true,});

Provider Lifecycle#

Flush and shut down the provider before process exit, otherwise in-flight batches can be lost.

process.on("SIGTERM", async () => {  await provider.shutdown();  process.exit(0);});

For short-lived processes such as scripts, CLI commands, and serverless handlers:

await doWork();await provider.shutdown();

Custom Span Processors#

If you need full control over export, pass your own spanProcessors. This replaces the default Phoenix exporter setup.

import { register } from "@arizeai/phoenix-otel";import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";const exporter = new OTLPTraceExporter({  url: "https://your-phoenix.example.com/v1/traces",  headers: { Authorization: `Bearer ${process.env.PHOENIX_API_KEY}` },});const provider = register({  projectName: "support-bot",  spanProcessors: [new BatchSpanProcessor(exporter)],});

Troubleshooting#

When traces do not show up in Phoenix, check these common issues:

confirm projectName is the project you are inspecting
confirm url or PHOENIX_COLLECTOR_ENDPOINT points at the collector
confirm PHOENIX_API_KEY is present for authenticated environments
confirm registration happens before the instrumented work starts
call await provider.shutdown() before process exit when using batched export

Enable Diagnostic Logging#

import { DiagLogLevel, register } from "@arizeai/phoenix-otel";const provider = register({  projectName: "support-bot",  batch: false,  diagLogLevel: DiagLogLevel.DEBUG,});await provider.shutdown();

Package Surface#

Category	Exports
Registration	`register()`, `attachGlobalTracerProvider()`, `detachGlobalTracerProvider()`, `createNoOpProvider()`
Tracing helpers	`withSpan()`, `traceChain()`, `traceAgent()`, `traceTool()`, `traceLLM()`, `traceRetriever()`, `traceReranker()`, `traceEmbedding()`, `traceGuardrail()`, `traceEvaluator()`, `tracePrompt()`, `observe()`
Context attributes	`setSession()`, `setUser()`, `setMetadata()`, `setTags()`, `setPromptTemplate()`, `setAttributes()`, `getAttributesFromContext()`
Attribute builders	`getLLMAttributes()`, `getToolAttributes()`, `getRetrieverAttributes()`, `getEmbeddingAttributes()`, `getMetadataAttributes()`
Redaction and safety	`OITracer`, `withSafety()`, `safelyJSONStringify()`, `safelyJSONParse()`
Semantic conventions	`SemanticConventions`, `OpenInferenceSpanKind`, `MimeType`
OpenTelemetry	`trace`, `context`, `SpanStatusCode`, `DiagLogLevel`, `suppressTracing`, `registerInstrumentations()`
Types	`Tracer`, `Instrumentation`, `SpanTraceOptions`, `RegisterParams`

Where To Start#

Tracing helpers for wrapping functions with withSpan, the span-kind wrappers (traceChain, traceAgent, traceTool, traceLLM, traceRetriever, traceReranker, traceEmbedding, traceGuardrail, traceEvaluator, tracePrompt), and observe
Context attributes for propagating sessions, users, metadata, tags, prompt templates, and manual context propagation
Manual spans for raw OpenTelemetry spans, attribute builders, OITracer, and utility helpers