Heuristic:Arize ai Phoenix Environment Variable Precedence

Knowledge Sources	Arize Phoenix Phoenix Engineering
Domains	Configuration, Debugging
Last Updated	2026-02-14 06:00 GMT

Overview

Phoenix configuration follows a strict precedence order: constructor arguments override environment variables, and Phoenix-specific env vars override standard OTel env vars.

Description

Phoenix uses a layered configuration system where values can be set at multiple levels. Understanding the resolution order prevents subtle misconfiguration bugs, especially when both Phoenix and standard OpenTelemetry environment variables are set.

The system also strips leading and trailing whitespace from all environment variable values, as these are assumed to be inadvertent. This is a defensive measure against copy-paste errors.

Usage

Apply this heuristic when:

Debugging connection issues between the client and server
Setting up Phoenix in environments where OTel is already configured
Understanding why a configuration change does not take effect

The Insight (Rule of Thumb)

Action: Follow this precedence order (highest to lowest):
1. Constructor arguments (`base_url`, `api_key`, `headers` parameters)
2. Phoenix-specific env vars (`PHOENIX_COLLECTOR_ENDPOINT`, `PHOENIX_API_KEY`)
3. Standard OTel env vars (`OTEL_EXPORTER_OTLP_ENDPOINT`)
4. Default values (`http://0.0.0.0:6006`)
Value: This applies to both the Python client and the OTel wrapper package.
Trade-off: Phoenix-specific env vars taking precedence over OTel standards can cause confusion if both are set. The intent is that Phoenix-specific configuration should always win for Phoenix-specific use cases.

Special behaviors:

Host `0.0.0.0` is auto-converted to `127.0.0.1` for client connections
`PHOENIX_API_KEY` is automatically added as `Authorization: Bearer <key>` unless an explicit `authorization` header exists in `PHOENIX_CLIENT_HEADERS`
Environment variable values are always stripped of whitespace

Reasoning

The resolution logic in `packages/phoenix-client/src/phoenix/client/utils/config.py:64-73`:

def get_env_collector_endpoint() -> Optional[str]:
    return getenv(ENV_PHOENIX_COLLECTOR_ENDPOINT) or getenv(ENV_OTEL_EXPORTER_OTLP_ENDPOINT)

def get_base_url() -> httpx.URL:
    host: str = get_env_host()
    if host == "0.0.0.0":
        host = "127.0.0.1"
    base_url: str = get_env_collector_endpoint() or f"http://{host}:{get_env_port()}"
    return httpx.URL(base_url)

The whitespace stripping from `config.py:80-100`:

def getenv(key: str, default: Optional[str] = None) -> Optional[str]:
    """Leading and trailing whitespaces are stripped from the value,
    assuming they were inadvertently added."""
    if (value := os.getenv(key)) is None:
        return default
    return value.strip()

Header merging in `client.py:265-278`:

def _update_headers(headers, api_key):
    headers = dict(headers or {})
    for k, v in get_env_client_headers().items():
        if k not in headers:          # env headers don't override explicit headers
            headers[k] = v
    if api_key:
        headers = {
            **{k: v for k, v in (headers or {}).items() if k.lower() != "authorization"},
            "Authorization": f"Bearer {api_key}",  # api_key always wins
        }
    return headers

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment