Phoenix Client
API for the Phoenix platform
Phoenix OTEL
OpenTelemetry tracing with Phoenix defaults
Phoenix Evals
LLM evaluation and metrics toolkit
OpenInference
Instrumentation and tracing helpers
Installation
Install all packages together or individually based on your needs:Environment Variables
Phoenix’s SDKs, thepx CLI, and MCP read their connection settings from environment variables. Two endpoint variables exist — one per concern, usually holding the same URL:
Any Phoenix instance that isn’t running on the same machine as your app — a container, a Kubernetes deployment, or a managed host — is reached the same way: point
PHOENIX_COLLECTOR_ENDPOINT at its hostname, and supply an API key if it has authentication enabled. That one variable covers tracing, the clients, and the px CLI.
register() exports traces over OTLP/gRPC to port 4317 on the same host. If the deployment does not expose that port, for example behind a reverse proxy or an ingress, pass protocol="http/protobuf" to register().
If you set only one, set PHOENIX_COLLECTOR_ENDPOINT. It configures tracing, and the clients and the px CLI use it for API access too — so one value covers everything. PHOENIX_ENDPOINT is the canonical setting for those client surfaces, and it wins when both are set, but you rarely need it on its own.
The fallback does not run both ways in every SDK. API access falls back to PHOENIX_COLLECTOR_ENDPOINT everywhere, but Python trace export does not yet read PHOENIX_ENDPOINT, so setting only PHOENIX_ENDPOINT can leave Python trace export pointed at http://localhost:6006.
Set PHOENIX_ENDPOINT as well only when trace ingest and API access live at different URLs.
PHOENIX_HOST is not a client setting — on the Phoenix server it is the bind host (e.g. 0.0.0.0, paired with PHOENIX_PORT). Some JS tools still accept it as a last-resort legacy fallback for the base URL, but new configuration should use the variables above.
Choosing a project
PHOENIX_PROJECT selects the project that project-scoped operations write to and read from. PHOENIX_PROJECT_NAME is a supported alias for the same setting. When both are set, PHOENIX_PROJECT wins and Phoenix logs a one-time conflict warning. If neither is set, the project defaults to "default".
The .env.phoenix file
Instead of exporting variables in every shell, you can drop PHOENIX_-prefixed settings into a .env.phoenix file. The Phoenix SDKs and CLI auto-discover it: starting from the current working directory they walk up toward the filesystem root and load the first .env.phoenix they find (dotenv format).
px setup writes: it records both endpoint variables (same value — one server) so trace export and API access are each explicit.
A few rules worth knowing:
-
The process environment always wins. A value already set in the environment is never overridden by the file.
Watch for endpoint variables exported globally — a
PHOENIX_ENDPOINTin your shell profile, or in~/.claude/settings.jsonfrom Claude Code tracing, applies in every directory and will shadow a project’s.env.phoenix. Ifpxor a client is reaching the wrong Phoenix, checkecho $PHOENIX_ENDPOINTfirst. Scope such variables to the session or project that needs them. -
The filename is
.env.phoenix, not.env. -
Add it to your ignore rules before storing credentials in it — the Phoenix repository already git-ignores
.env.phoenix. -
Opt out by setting
PHOENIX_DISCOVER_CONFIG=false(also accepts0,no,off), which disables file discovery entirely.
Phoenix Client
- Prompts — Create, version, and invoke prompt templates with variable substitution
- Datasets — Build evaluation datasets from DataFrames, CSV files, or dictionaries
- Experiments — Run evaluations and track experiment results over time
- Spans — Query and analyze traces with powerful filtering capabilities
- Annotations — Add human feedback and automated evaluations to spans
- Projects — Organize your work across multiple AI applications
Usage Guide
Examples and getting started
API Reference
Full API documentation
Phoenix OTEL
- Zero-config tracing — Enable
auto_instrument=Trueto automatically trace AI libraries - Phoenix-aware defaults — Reads
PHOENIX_COLLECTOR_ENDPOINT,PHOENIX_API_KEY, and other environment variables - Production ready — Built-in batching and authentication support
- Tracing decorators —
@tracer.chain,@tracer.tool, and more for manual instrumentation - OpenTelemetry compatible — Works with existing OTel infrastructure
Usage Guide
Examples and getting started
API Reference
Full API documentation
Phoenix Evals
- Model adapters — Works with OpenAI, LiteLLM, LangChain, and other providers
- Pre-built metrics — Faithfulness detection, relevance, toxicity, and more
- Input mapping — Powerful binding for complex data structures
- Native instrumentation — OpenTelemetry tracing for observability
- High performance — Up to 20x speedup with built-in concurrency and batching
Usage Guide
Examples and getting started
API Reference
Full API documentation
OpenInference
- Decorators — Use
@tracer.agent,@tracer.chain,@tracer.toolto trace custom functions - Context managers — Wrap code blocks with
using_helpers for fine-grained control - Data masking — Redact sensitive information from traces with built-in masking utilities
- Framework instrumentors — Auto-trace OpenAI, LangChain, LlamaIndex, Anthropic, and more
Usage Guide
Examples and getting started
GitHub
Source code and documentation

