Registry / llm-agents / arize-phoenix

arize-phoenix

JSON →
library13.3.0pypypi✓ verified 50d ago

Open-source AI observability and evaluation platform from Arize AI. Phoenix provides tracing, evaluation, prompt management, datasets, and experiments for LLM applications. Built on OpenTelemetry and OpenInference. Can be run locally, self-hosted (Docker/K8s), or accessed via cloud at app.phoenix.arize.com. CRITICAL: Phoenix is a separate product from Arize AX (the enterprise cloud platform). They share the Arize brand but use different packages, credentials, and endpoints: Phoenix uses phoenix.otel + PHOENIX_API_KEY; Arize AX uses arize.otel + ARIZE_SPACE_ID + ARIZE_API_KEY. arize-phoenix is the full-platform bundle. For production deployments, the modular sub-packages (arize-phoenix-otel, arize-phoenix-client, arize-phoenix-evals) are preferred. LICENSE: Elastic License 2.0 (ELv2) — NOT MIT/Apache. Restrictions apply to providing Phoenix as a managed service to third parties.

llm-agentsai-mlobservabilitydevops
pip install arize-phoenix
Install & Compatibility
Where this runs
tested against v17.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
5/20 runs
17/20 runs
py 3.11
5/20 runs
17/20 runs
py 3.12
5/20 runs
17/20 runs
py 3.13
5/20 runs
17/20 runs
py 3.9
5/20 runs
5/20 runs
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

register (phoenix.otel)
from phoenix.otel import register
from arize.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
from arize import ArizeClient
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).

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'] )
phoenix --version
Debug
Known issues
breakingPhoenix (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.
affects: all
breakingauto_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.
affects: all
gotchaarize-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.
affects: all
gotchapip 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.
affects: all
gotchaPHOENIX_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>'.
affects: all
gotchaBy 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.
affects: all
breakingInstalling `arize-phoenix` (and its dependencies like `sqlean-py`) requires a C compiler to build certain packages from source if pre-built wheels are not available for your specific Python version and platform. The installation will fail with 'command 'gcc' failed: No such file or directory'. This often occurs in minimal or 'slim' Docker images.
fix
Ensure a C compiler and build tools are installed in your environment. For Debian/Ubuntu-based systems, add `RUN apt-get update && apt-get install -y build-essential` to your Dockerfile, or consider using a Python base image that includes these tools (e.g., `python:3.9` instead of `python:3.9-slim`).
affects: all
breakingInstalling `arize-phoenix` (or its dependencies like `scikit-learn`) on minimal Linux distributions such as Alpine may fail due to missing build tools. Python packages with native extensions, like `scikit-learn`, require a C/C++ compiler and development headers to be present in the environment for successful installation.
fix
For Alpine Linux, install the necessary build tools before attempting `pip install`: `apk add build-base python3-dev`. For Debian/Ubuntu, use `apt-get install build-essential python3-dev`.
affects: all
Errors
Common errors & fixes
ImportError: cannot import name 'version' from 'phoenix.version'
This error occurs when attempting to import 'version' from 'phoenix.version', but the 'version' attribute does not exist in that module.
fix
Ensure that you are importing the correct attribute from 'phoenix.version'. If 'version' is not available, check the module's documentation or source code for the correct attribute to import.
ModuleNotFoundError: No module named 'arize'
This error indicates that the 'arize' module is not installed in your Python environment.
fix
Install the 'arize' module using pip: 'pip install arize'.
ModuleNotFoundError: No module named 'phoenix'
This error occurs when the 'phoenix' module is not installed or not found in your Python environment.
fix
Install the 'phoenix' module using pip: 'pip install arize-phoenix'.
Upgrade
Version history
17.2.0latest on PyPI
Audit
Dependencies

No dependency data recorded yet.

Agent activity
121 hits · last 30 days
node
17
petalbot
6
bytedance
3
seranking-bot
3
ahrefsbot
2
amazonbot
2
applebot
1
sogoubot
1
yandexbot
1
Resources