Phoenix’s Python SDK is modular by design, allowing you to install only what you need. Each package serves a specific purpose and can be used independently or together.
Installation#
Install all packages together or individually based on your needs:
Environment Variables#
All packages respect common Phoenix environment variables for seamless configuration:
| Variable | Description | Used By |
|---|---|---|
PHOENIX_ENDPOINT | Phoenix base URL — canonical for everything except trace export | Client, CLI |
PHOENIX_COLLECTOR_ENDPOINT | Base Phoenix collector URL or full OTLP trace endpoint | OTEL (Client and CLI infer from it when PHOENIX_ENDPOINT is unset) |
PHOENIX_API_KEY | API key for authentication | Client, OTEL |
PHOENIX_PROJECT | Default project name (canonical) | Client, OTEL, CLI |
PHOENIX_PROJECT_NAME | Alias for PHOENIX_PROJECT; PHOENIX_PROJECT wins if both are set | Client, OTEL |
PHOENIX_CLIENT_HEADERS | Custom HTTP headers | Client, OTEL |
PHOENIX_DISCOVER_CONFIG | Set to false to disable .env.phoenix credential-file discovery | Client, OTEL, CLI |
Phoenix SDKs and the CLI also auto-load PHOENIX_-prefixed settings from a .env.phoenix file, discovered by walking up from the current directory. Process environment variables always take precedence. See Environments.
Phoenix Client#
The Phoenix Client provides a programmatic interface to the Phoenix platform via its REST API. Use it to manage datasets, run experiments, analyze traces, and collect feedback.
- 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
Phoenix OTEL#
Phoenix OTEL provides a lightweight wrapper around OpenTelemetry primitives with Phoenix-aware defaults. It simplifies tracing setup and provides decorators for common GenAI patterns.
- 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
Phoenix Evals#
Phoenix Evals provides lightweight, composable building blocks for evaluating LLM applications. It includes tools for relevance scoring, faithfulness detection, toxicity checks, and custom metrics.
- 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
OpenInference#
OpenInference provides instrumentation utilities and helpers for tracing AI applications. Use it alongside Phoenix OTEL for decorators, context managers, and data masking capabilities.
- 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