Tracing

Traces let you see what’s happening inside your application—LLM calls, tool invocations, retrieval steps, and more. This guide walks you through sending your first traces to Phoenix.

1. 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.

2. Install the Phoenix OTEL package and an instrumentation library. This quickstart uses OpenAI, but Phoenix supports many providers and frameworks including Anthropic, LangChain, LlamaIndex, Vercel AI SDK, Mastra, and more.

   Python

   pip install arize-phoenix-otel openinference-instrumentation-openai openai
   

   See all Python integrations.

   TypeScript

   npm install @arizeai/phoenix-otel @arizeai/openinference-core @arizeai/openinference-instrumentation-openai openai
   

   See all TypeScript integrations.

3. Register Phoenix as your trace collector. The register function configures your application to export spans to Phoenix and auto-instruments supported libraries.

   Python

   from phoenix.otel import register
   
   tracer_provider = register(
       project_name="my-llm-app",
       auto_instrument=True,  # Auto-instruments OpenAI, LangChain, etc.
       batch=False,  # Send spans immediately (recommended for local dev)
   )
   

   See the arize-phoenix-otel reference for all options.

   TypeScript

   Create an instrumentation.ts file:

   import OpenAI from "openai";
   import { register, registerInstrumentations } from "@arizeai/phoenix-otel";
   import { OpenAIInstrumentation } from "@arizeai/openinference-instrumentation-openai";
   
   register({ projectName: "my-llm-app", batch: false });
   
   const instrumentation = new OpenAIInstrumentation();
   instrumentation.manuallyInstrument(OpenAI);
   
   registerInstrumentations({
     instrumentations: [instrumentation],
   });
   

   Import this file at the top of your entrypoint:

   import "./instrumentation";
   

   TypeScript tracing setup varies based on your module system (ESM vs CommonJS), runtime (Node.js, Bun, Deno), and framework (Next.js, Express, etc.). For detailed configuration options including batching, gRPC, and advanced setups, see the complete tracing setup guide.

   See the @arizeai/phoenix-otel reference for all options.

   Local vs Production: We set batch=False here so traces appear immediately—ideal for local development. In production, use batch=True (the default) for better performance. See the SDK reference for configuration options like batching, gRPC transport, and custom headers.

4. Make an LLM call to generate your first trace. OpenAI calls are automatically captured:

   Python

   import openai
   
   client = openai.OpenAI()
   response = client.chat.completions.create(
       model="gpt-4o",
       messages=[{"role": "user", "content": "Why is the sky blue?"}],
   )
   print(response.choices[0].message.content)
   

   Use @tracer.agent, @tracer.tool, and @tracer.chain decorators to create custom spans around your own functions. See the tracing guide for details.

   TypeScript

   import "./instrumentation";
   import OpenAI from "openai";
   
   const openai = new OpenAI();
   const response = await openai.chat.completions.create({
     model: "gpt-4o",
     messages: [{ role: "user", content: "Why is the sky blue?" }],
   });
   console.log(response.choices[0].message.content);
   

   Use traceAgent, traceTool, and withSpan wrappers to create custom spans around your own functions. See the tracing guide for details.

5. Open Phoenix to see your traces:

   

Next Steps

Tracing Concepts

Understand spans, traces, and how observability works

Add Metadata & Tags

Enrich traces with custom attributes for filtering and analysis

Integrations

Connect LangChain, LlamaIndex, Anthropic, and 20+ frameworks

Manual Instrumentation

Add custom spans with decorators and wrappers

Run Evaluations

Score your traces with LLM-as-a-judge evaluators

Advanced Setup

Configure batching, gRPC, headers, and more