OpenTelemetry Exporter Configuration: JS vs. Python Endpoint Handling#

PHOENIX_COLLECTOR_ENDPOINT is interpreted differently by Python and JavaScript SDKs. This mismatch causes silent trace loss for any JS user who follows documentation or examples written for the Python behavior.

The Core Difference#

Python (src/phoenix/trace/exporter.py): The _OpenInferenceExporter class reads PHOENIX_COLLECTOR_ENDPOINT via get_env_collector_endpoint(), ensures a trailing slash, then calls urljoin(base_url, "v1/traces") before passing the result to OTLPSpanExporter 1.

The phoenix-otel package does the same — _construct_http_endpoint() always replaces the URL path with /v1/traces, and _normalized_endpoint() applies this transformation when the env var is read 2 3.

JavaScript (@arizeai/openinference-mastra): OpenInferenceOTLPTraceExporter is a thin wrapper around @opentelemetry/exporter-trace-otlp-proto's OTLPTraceExporter. The constructor accepts a url option and passes it through with no modification 4. The README shows the correct usage pattern — passing the URL directly from the env var:

url: process.env.PHOENIX_COLLECTOR_ENDPOINT,

5

The README documentation explicitly sets PHOENIX_COLLECTOR_ENDPOINT to the full URL including /v1/traces 6:

export PHOENIX_COLLECTOR_ENDPOINT="https://localhost:6006/v1/traces"

The Failure Mode#

When a user sets PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006 (the Python convention), the JS exporter POSTs to the base URL. Phoenix has no handler at /, the request fails, and the batch exporter silently swallows the delivery error — the application looks healthy throughout 7.

This is especially dangerous in containerized environments, where the collector endpoint is typically set to a bare host by construction (e.g., http://phoenix:6006). Every Mastra run will fail identically and silently until the endpoint is corrected 8.

The issue was first confirmed during onboarding testing against the no-observability/mastra repository 8.

Fix#

Immediate fix: Set PHOENIX_COLLECTOR_ENDPOINT to the full OTLP path when using a JS exporter:

# For JS/Mastra (include the path)
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006/v1/traces

# For Python (base URL only — path is appended automatically)
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006

Planned fix: Normalize the endpoint inside the JS exporter itself, so it checks for the /v1/traces suffix and appends it if missing. A cheaper interim path is having px setup write the suffixed endpoint when it detects a JS target 7.

Related Issues#

• #14875 — Tracking issue for the exporter normalization fix 7
• #14876 — px setup verification may report success without a landed trace 9
• #14877 — Project-name redirect shows a bare error when the project doesn't exist 10

Key Source Files#