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 provider. This connects your app to Phoenix and 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.
   )
   

   See the Python SDK 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" });
   
   const instrumentation = new OpenAIInstrumentation();
   instrumentation.manuallyInstrument(OpenAI);
   
   registerInstrumentations({
     instrumentations: [instrumentation],
   });
   

   Import this file at the top of your entrypoint:

   import "./instrumentation";
   

   See the TypeScript SDK reference for all options.

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);
   
   // Allow time for traces to flush
   await new Promise((resolve) => setTimeout(resolve, 5000));
   

   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

Add Metadata & Tags