fix(js): prevent global tracer provider collisions across experiment phases

[mikeldking]

Summary

• Problem: When runExperiment runs tasks then evaluators, each phase calls provider.register() to set itself as the global OTEL tracer provider. The second call silently replaces the first, causing task-phase spans to be orphaned and preventing clean shutdown of the first provider.
• Adds attachGlobalTracerProvider / detachGlobalTracerProvider to phoenix-otel — these snapshot the current global OTEL state before mounting a new provider and restore it on detach, so multiple providers can safely take turns owning the global slot (stack-like semantics with out-of-order detach support).
• Splits provider creation from global registration in experiment code (runExperiment, resumeExperiment, resumeEvaluation) — each phase now calls register({ global: false }) then explicitly attachGlobalTracerProvider(), and wraps its body in try/finally to guarantee forceFlush → shutdown → detach even on errors.
• Makes phoenix-evals tracer dynamic — instead of capturing a static tracer at module load, the tracer now resolves from trace.getTracer() at call time so evaluator spans follow whichever provider is currently mounted as global.
• Fixes pnpm proxy mismatch — NodeTracerProvider.register() calls trace.setGlobalTracerProvider() using the SDK's internal import of @opentelemetry/api, which in pnpm workspaces can resolve to a different module instance (different symlink paths → different TraceAPI singletons). This caused snapshot/restore to operate on the wrong proxy, leaving the user's original provider unrestored. Fixed by routing all global state mutations through phoenix-otel's own trace/context/propagation imports via a new setGlobalProvider() helper.

Test plan

• New tests in phoenix-otel verify sequential attach/detach, restore of external provider, and out-of-order detach
• New test in phoenix-client (runExperimentTracing.test.ts) verifies task and eval phases get separate providers and both are properly cleaned up
• New tests in phoenix-evals verify evaluator spans follow the current global provider across provider swaps (both createEvaluator and createClassificationEvaluator)
• Existing experiment tests updated with attachGlobalTracerProvider mock and shutdown mock
• Integration test (integration-tracer-collision.ts) validated against live Phoenix at localhost:6006 — creates dataset, runs experiment with 3 examples and 2 evaluators, verifies spans land in correct projects, and confirms the user's pre-existing global provider is properly restored after the experiment completes

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
arize-phoenix	🟢 Ready	View Preview	Mar 21, 2026, 4:52 PM

[pkg-pr-new]

Open in StackBlitz

@arizeai/phoenix-cli

npm i https://pkg.pr.new/@arizeai/phoenix-cli@12303

@arizeai/phoenix-client

npm i https://pkg.pr.new/@arizeai/phoenix-client@12303

@arizeai/phoenix-evals

npm i https://pkg.pr.new/@arizeai/phoenix-evals@12303

@arizeai/phoenix-mcp

npm i https://pkg.pr.new/@arizeai/phoenix-mcp@12303

@arizeai/phoenix-otel

npm i https://pkg.pr.new/@arizeai/phoenix-otel@12303

commit: 5642cd4

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[mikeldking]

Code Review

What this PR accomplishes

This PR fixes a global OTel tracer provider collision that occurs when runExperiment executes tasks then evaluators sequentially — each phase previously called provider.register(), silently replacing the first provider and orphaning task-phase spans.

Core changes:

1. Stack-based mount system in phoenix-otel — attachGlobalTracerProvider() / detachGlobalTracerProvider() snapshot the pre-existing global OTel state before mounting a new provider and restore it on detach. This allows multiple providers to safely take turns owning the global slot without losing the user's original provider.

2. Explicit provider lifecycle in experiment code — All three entry points (runExperiment, resumeExperiment, resumeEvaluation) now create providers with global: false, attach/detach explicitly, and use try/finally to guarantee forceFlush → shutdown → detach even on errors.

3. Dynamic tracer in phoenix-evals — The tracer now resolves from trace.getTracer() at call time instead of capturing a static tracer at module load, so evaluator spans follow whichever provider is currently mounted.

4. pnpm module identity fix — All global state mutations route through phoenix-otel's own OTel API imports via setGlobalProvider(), avoiding the symlink-driven module identity divergence in pnpm workspaces.

Review updates (4c5b972)

• Replaced arguments + unused named params in phoenix-evals dynamic tracer proxy with explicit ...args rest params for clarity
• Added JSDoc on the lazy tracer factory explaining the pattern and the as Tracer cast
• Added comments on the finally-block cleanup calls in runExperiment and resumeExperiment explaining they are safety nets for error paths (no-ops on the happy path)

Remaining notes for reviewers

• Lock file churn: The pnpm-lock.yaml changes include version drifts (e.g., @types/node 25.5.0 → 25.2.3, oxlint 1.56.0 → 1.53.0). Verify these are intentional and won't cause issues on main.
• Skill files: The .agents/skills/ documentation adds ~600 lines. Consider splitting into a separate PR if you want a lighter review.
• Integration test timing: The 2-second setTimeout for span export could be flaky in CI — forceFlush() on the sentinel provider would be more reliable.