Arize Phoenix (arize-phoenix)

Warnings

• breaking Phoenix (arize-phoenix) and Arize AX (arize) are two completely different products that share the Arize brand. They have different packages, different credentials, different endpoints, and different import paths. The most dangerous confusion: both have a register() function (phoenix.otel.register vs arize.otel.register) that look identical but export to completely different backends. Using the wrong one sends traces to the wrong service silently with no error.
  Fix: Phoenix: from phoenix.otel import register + PHOENIX_API_KEY + PHOENIX_COLLECTOR_ENDPOINT. Arize AX: from arize.otel import register + ARIZE_API_KEY + ARIZE_SPACE_ID. Confirm which product you have an account for before writing any code.
• breaking auto_instrument=True in register() does NOT work out of the box. It only instruments providers for which you have separately installed the corresponding openinference-instrumentation-* package. For example, to auto-trace OpenAI calls, you must install openinference-instrumentation-openai separately. If the instrumentation package is absent, auto_instrument silently skips that provider.
  Fix: Install the specific instrumentors you need: pip install openinference-instrumentation-openai openinference-instrumentation-anthropic openinference-instrumentation-langchain etc. Or install all at once: pip install openinference-instrumentation.
• gotcha arize-phoenix is licensed under Elastic License 2.0 (ELv2), NOT MIT or Apache. ELv2 prohibits providing Phoenix as a managed service to third parties (i.e., you cannot resell or host Phoenix as a product feature that your own customers access directly). Internal use and self-hosting for your own team are fully permitted.
  Fix: For SaaS products where your customers would access Phoenix UI/APIs directly, consult Arize AI about a commercial license. For internal observability tooling, ELv2 permits free self-hosting.
• gotcha pip install arize-phoenix installs the full platform bundle including a FastAPI server, SQLite/PostgreSQL ORM, and a bundled React frontend — it's a heavy install (~100MB+). In production app code (your LLM service), you almost never want the full bundle. You only need arize-phoenix-otel (for tracing) and/or arize-phoenix-client (for querying).
  Fix: In app service requirements.txt: pip install arize-phoenix-otel arize-phoenix-client. Reserve pip install arize-phoenix for the dedicated Phoenix server process.
• gotcha PHOENIX_CLIENT_HEADERS uses equals-sign-separated key=value format (matching OTel conventions), not HTTP colon-separated format. PHOENIX_CLIENT_HEADERS='Authorization=Bearer token' is correct. Using 'Authorization: Bearer token' (colon) silently fails.
  Fix: Always use equals sign: PHOENIX_CLIENT_HEADERS='Authorization=Bearer <token>'.
• gotcha By default, arize-phoenix collects basic web analytics (page views, UI interactions) from the Phoenix UI. This applies to the hosted server only — not to trace data or LLM inputs/outputs. Self-hosted instances have this disabled by default as of recent versions.
  Fix: If analytics collection is a concern for self-hosted deployments, review your version's telemetry settings. Trace data and LLM content are never collected by Phoenix's own telemetry.

Install

• pip install arize-phoenix Full platform (server + all APIs) — for local dev / self-hosting
• pip install arize-phoenix-otel arize-phoenix-client arize-phoenix-evals Modular install — preferred for production app code against a deployed Phoenix server
• pip install 'arize-phoenix[evals]' Full platform + evals extra
• pip install 'arize-phoenix[pg]' Full platform + PostgreSQL backend (instead of default SQLite)

Imports

• register (phoenix.otel)

  from phoenix.otel import register

  Phoenix OTel registration. arize.otel.register sends to Arize AX. phoenix.otel.register sends to Phoenix. They look identical — wrong import sends traces to the wrong backend silently.
• Client (phoenix.client)

  from phoenix.client import Client

  Phoenix REST client. ArizeClient is for Arize AX. Different platforms, different credentials.
• llm_classify (evals)

  from phoenix.evals import llm_classify, OpenAIModel

  Primary evaluation API. Requires arize-phoenix-evals installed separately (not included in arize-phoenix-otel).

Quickstart

For local dev, px.launch_app() starts the Phoenix server in-process. For production deployments, run Phoenix as a separate service (Docker/K8s) and use the modular sub-packages in your app code. Never mix Phoenix and Arize AX credentials.

# === OPTION A: Local dev (run Phoenix server + instrument your app) ===

# 1. Launch Phoenix server locally
import phoenix as px
px.launch_app()  # Opens UI at http://localhost:6006

# 2. Instrument with OTel
from phoenix.otel import register
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer_provider = register(
    project_name='my-app',
    # auto_instrument=True  # Only works if openinference-instrumentation-* pkgs are installed
)
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

import openai
client = openai.OpenAI()
response = client.chat.completions.create(
    model='gpt-4o',
    messages=[{'role': 'user', 'content': 'Hello!'}]
)
# Trace visible in Phoenix UI at http://localhost:6006

# === OPTION B: Production (app code → deployed Phoenix server) ===
import os
os.environ['PHOENIX_COLLECTOR_ENDPOINT'] = 'https://app.phoenix.arize.com/s/my-space'
os.environ['PHOENIX_API_KEY'] = 'your-phoenix-api-key'

from phoenix.otel import register
tracer_provider = register(project_name='prod-app', batch=True)
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)

# === Phoenix Client (REST API) ===
from phoenix.client import Client
ph = Client()  # reads PHOENIX_BASE_URL and PHOENIX_API_KEY from env

# Query traces
spans = ph.spans.query(project_name='my-app')

# === Evaluations ===
from phoenix.evals import llm_classify, OpenAIModel
model = OpenAIModel(model='gpt-4o')
results = llm_classify(
    dataframe=spans_df,
    model=model,
    template='hallucination',  # built-in template
    rails=['factual', 'hallucinated']
)