skills.rest
Arize-ai
Arize-aiOFFICIAL
Explore all skills by this author →
Website𝕏@arizeaiGitHub

phoenix-otel-development

Guides OpenTelemetry registration and global tracer provider lifecycle management in TypeScript.

11.3k|1.1k|Updated Nov 9, 2022
Search Tags:#Vitest#tracing#typeScript#Phoenix#openTelemetry#provider lifecycle#pnpm workspace
One-click install
npx skills add https://github.com/Arize-ai/phoenix --skill phoenix-otel-development
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: phoenix-otel-development
Source: https://github.com/Arize-ai/phoenix/tree/main/js/packages/phoenix-otel/.agents/skills/phoenix-otel-development
Command: npx skills add https://github.com/Arize-ai/phoenix --skill phoenix-otel-development

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @opentelemetry/api, @arizeai/openinference-vercel, vitest, and includes references (resource) components.

What problem does it solve?

Managing OpenTelemetry global providers in pnpm workspaces is error-prone because different packages may resolve different module instances of @opentelemetry/api, causing inconsistent global state. This Skill provides the conventions and invariants for safely registering, attaching, detaching, and testing tracer providers through the phoenix-otel package.

Core Features & Use Cases

  • Global Provider Lifecycle: Stack-based mount system for attaching and detaching global tracer providers with base snapshot capture and restore.
  • register() API Guidance: Rules for the global parameter, span processor setup via @arizeai/openinference-vercel, and environment variable fallbacks (PHOENIX_COLLECTOR_ENDPOINT, PHOENIX_API_KEY).
  • Testing Conventions: Patterns for testing with real OTel components and spy span processors, including mandatory cleanup via detach in afterEach.
  • Use Case: When adding a new feature to phoenix-client experiments that needs tracing without global attachment, follow the register() rules to call it with global: false and manage attachment explicitly.

Quick Start

Ask the AI to read the relevant rule file and help you register a tracer provider with phoenix-otel using the correct global attachment pattern.

Frequently Asked Questions about phoenix-otel-development

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I register an OpenTelemetry tracer provider in a pnpm workspace?▼

Use the register() function from phoenix-otel rather than calling provider.register() directly. In pnpm workspaces, packages may resolve different @opentelemetry/api module instances, so all global state mutations must go through this module's own OTel imports.

What does the global parameter do in phoenix-otel register()?▼

With global: true (the default), the provider is attached to OTel globals and shutdown() automatically detaches it. With global: false, the provider is not attached and callers manage attachment explicitly via attachGlobalTracerProvider(), as phoenix-client experiments do.

Why does OpenTelemetry global state differ between packages in pnpm?▼

Pnpm symlinks cause packages importing @opentelemetry/api to resolve different module instances with different identities. If one package registers through the SDK's import and another reads globals through its own import, they see different state.

How do I test OpenTelemetry provider lifecycle code?▼

Use real OTel components with spy span processors instead of mocks, and never mock @opentelemetry/api or NodeTracerProvider. Every test touching global state must call detachGlobalTracerProvider() in afterEach to avoid leaking mounts into subsequent tests.

Which span processors does phoenix-otel use?▼

Span processors come from @arizeai/openinference-vercel, specifically OpenInferenceBatchSpanProcessor and OpenInferenceSimpleSpanProcessor, not from @opentelemetry/sdk-trace-base. You can also pass custom processors via the spanProcessors option.

What happens when detach is called out of order on the provider stack?▼

Non-topmost detaches are safe but ineffective: the mount is removed from the stack but globals remain unchanged until the top mount detaches. Out-of-order detach never corrupts global state and is silently ignored.

Related Skills

Explore More Software Engineering Skills→
kagentikagenti
292

auth:otel-oauth2-exporter

Configure the OpenTelemetry Collector with OAuth2 client credentials for trace export.

Official
Intermediate
qcmuuqcmuu

phoenix-observability

Capture OpenTelemetry traces and evaluation results for LLM debugging.

Community
Advanced
davidrrowleydavidrrowley

azure-monitor-opentelemetry-ts

Instruments Node.js services with Azure Monitor OpenTelemetry to collect traces, metrics, and logs.

Community
Advanced
BagelHoleBagelHole
46

opentelemetry

Instrument applications and infrastructure with OpenTelemetry for unified traces, metrics, and logs.

Community
Intermediate