@arizeai/phoenix-otel 0.4.2 → 0.4.3

package/docs/manual-spans.mdx

@@ -0,0 +1,99 @@
+---
+title: "Manual Spans"
+description: "Create manual spans with @arizeai/phoenix-otel"
+---
+
+The package re-exports `trace`, `context`, and `SpanStatusCode` from OpenTelemetry so you can create custom spans after registration without pulling them from another package.
+
+For most use cases, prefer the `@arizeai/openinference-core` helpers (`withSpan`, `traceChain`, `traceAgent`, `traceTool`) over raw `startActiveSpan`. They automatically set the correct OpenInference span kind, handle errors, and close the span for you.
+
+<section className="hidden" data-agent-context="relevant-source-files" aria-label="Relevant source files">
+  <h2>Relevant Source Files</h2>
+  <ul>
+    <li><code>src/index.ts</code></li>
+  </ul>
+</section>
+
+## Recommended — OpenInference Helpers
+
+```bash
+npm install @arizeai/openinference-core @arizeai/openinference-semantic-conventions
+```
+
+```ts
+import { withSpan, setSession, setMetadata } from "@arizeai/openinference-core";
+import { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";
+import { context } from "@opentelemetry/api";
+import { register } from "@arizeai/phoenix-otel";
+
+register({ projectName: "support-bot" });
+
+const retrieveDocs = withSpan(
+  async (query: string) => {
+    const response = await fetch(`/api/search?q=${query}`);
+    return response.json();
+  },
+  { name: "retrieve-docs", kind: OpenInferenceSpanKind.RETRIEVER }
+);
+
+const generateAnswer = withSpan(
+  async (query: string, docs: string[]) => {
+    return `Answer based on ${docs.length} documents`;
+  },
+  { name: "generate-answer", kind: OpenInferenceSpanKind.LLM }
+);
+
+const ragPipeline = withSpan(
+  async (query: string) => {
+    const docs = await retrieveDocs(query);
+    return generateAnswer(query, docs);
+  },
+  { name: "rag-pipeline", kind: OpenInferenceSpanKind.CHAIN }
+);
+
+// Session and metadata propagate to all child spans
+await context.with(
+  setMetadata(
+    setSession(context.active(), { sessionId: "session-abc-123" }),
+    { environment: "production" }
+  ),
+  () => ragPipeline("What is Phoenix?")
+);
+```
+
+## Raw OpenTelemetry Spans
+
+Use raw spans when you need full control over attributes and timing:
+
+```ts
+import {
+  SpanStatusCode,
+  register,
+  trace,
+} from "@arizeai/phoenix-otel";
+
+register({ projectName: "support-bot" });
+
+const tracer = trace.getTracer("support-bot");
+
+await tracer.startActiveSpan("lookup-customer", async (span) => {
+  try {
+    span.setAttribute("customer.id", "cust_123");
+    await Promise.resolve();
+  } catch (error) {
+    span.recordException(error as Error);
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    throw error;
+  } finally {
+    span.end();
+  }
+});
+```
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/index.ts</code></li>
+    <li><code>src/register.ts</code></li>
+  </ul>
+</section>

package/docs/overview.mdx

@@ -0,0 +1,248 @@
+---
+title: "Overview"
+description: "Bundled docs for @arizeai/phoenix-otel"
+---
+
+`@arizeai/phoenix-otel` is the Phoenix-focused OpenTelemetry package for Node.js. It wraps provider setup, span export, instrumentation registration, and a few convenience utilities for Phoenix-specific tracing workflows.
+
+## Install
+
+Install the package and any OpenTelemetry instrumentations you want to use with it.
+
+```bash
+npm install @arizeai/phoenix-otel
+```
+
+### Recommended — Add OpenInference Core
+
+`@arizeai/openinference-core` provides tracing helpers (`withSpan`, `traceChain`, `traceAgent`, `traceTool`), decorators (`@observe`), and context setters (`setSession`, `setUser`, `setMetadata`, `setTag`) that work on top of the provider registered by phoenix-otel. Install it alongside phoenix-otel for the best tracing experience.
+
+```bash
+npm install @arizeai/phoenix-otel @arizeai/openinference-core
+```
+
+### Add Instrumentations
+
+```bash
+npm install \
+  @arizeai/phoenix-otel \
+  @opentelemetry/instrumentation-http \
+  @opentelemetry/instrumentation-express
+```
+
+### Typical Pairings
+
+- `@arizeai/phoenix-otel` plus `@arizeai/openinference-core` for manual tracing with span-kind helpers and context propagation
+- `@arizeai/phoenix-otel` plus OpenTelemetry instrumentations for automatic framework tracing
+- `@arizeai/phoenix-otel` plus `@arizeai/phoenix-client` for experiment workflows
+- `@arizeai/phoenix-otel` plus framework-specific OpenInference instrumentors (e.g. `@arizeai/openinference-instrumentation-openai`)
+
+## Quick Start
+
+```ts
+import { register } from "@arizeai/phoenix-otel";
+import { withSpan } from "@arizeai/openinference-core";
+import { OpenInferenceSpanKind } from "@arizeai/openinference-semantic-conventions";
+
+const provider = register({ projectName: "support-bot" });
+
+const handleQuery = withSpan(
+  async (query: string) => {
+    return `Handled: ${query}`;
+  },
+  { name: "handle-query", kind: OpenInferenceSpanKind.CHAIN }
+);
+
+await handleQuery("Hello");
+await provider.shutdown();
+```
+
+## Docs And Source In `node_modules`
+
+After install, a coding agent can inspect the installed package directly:
+
+```text
+node_modules/@arizeai/phoenix-otel/docs/
+node_modules/@arizeai/phoenix-otel/src/
+```
+
+The bundled docs cover configuration, instrumentation, manual spans, and troubleshooting.
+
+## Configuration
+
+`register()` can use explicit options, environment variables, or both. If you pass a Phoenix base URL, the package normalizes it to the OTLP collector endpoint at `/v1/traces`.
+
+### Environment-Driven Setup
+
+```bash
+export PHOENIX_COLLECTOR_ENDPOINT=http://localhost:6006
+export PHOENIX_API_KEY=<your-api-key>
+```
+
+```ts
+import { register } from "@arizeai/phoenix-otel";
+
+const provider = register({
+  projectName: "support-bot",
+});
+```
+
+### Explicit Setup
+
+```ts
+import { DiagLogLevel, register } from "@arizeai/phoenix-otel";
+
+const provider = register({
+  projectName: "support-bot",
+  url: "https://app.phoenix.arize.com",
+  apiKey: process.env.PHOENIX_API_KEY,
+  headers: {
+    "x-client-name": "support-bot-api",
+    "x-client-version": "1.4.2",
+  },
+  batch: true,
+  diagLogLevel: DiagLogLevel.INFO,
+});
+```
+
+### Key Options
+
+| Option | Description |
+|--------|-------------|
+| `projectName` | Phoenix project name attached to exported spans. Defaults to `default`. |
+| `url` | Phoenix base URL or full collector endpoint. The package appends `/v1/traces` when needed. |
+| `apiKey` | API key sent as a bearer token. Falls back to `PHOENIX_API_KEY`. |
+| `headers` | Additional OTLP headers merged with the auth header. |
+| `batch` | `true` for batched export, `false` for immediate export during debugging. |
+| `instrumentations` | OpenTelemetry instrumentations to register with the provider. |
+| `spanProcessors` | Custom span processors. When provided, these replace the default Phoenix exporter setup. |
+| `global` | Whether to attach the provider to the global OpenTelemetry APIs automatically. |
+| `diagLogLevel` | OpenTelemetry diagnostic logging level. |
+
+### Environment Variables
+
+| Variable | Use |
+|--------|-----|
+| `PHOENIX_COLLECTOR_ENDPOINT` | Base Phoenix collector URL or full OTLP trace endpoint. |
+| `PHOENIX_API_KEY` | API key used when you do not pass `apiKey` explicitly. |
+
+## Instrumentation
+
+Pass OpenTelemetry instrumentations to `register()` to capture framework and library activity automatically.
+
+```ts
+import { register } from "@arizeai/phoenix-otel";
+import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
+import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
+
+register({
+  projectName: "support-bot",
+  instrumentations: [
+    new HttpInstrumentation(),
+    new ExpressInstrumentation(),
+  ],
+});
+```
+
+- the package also re-exports `registerInstrumentations`
+- auto-instrumentation setups often work best when they are initialized very early in process startup
+- for custom providers, you can pass your own `spanProcessors`
+
+## Production
+
+### Enable Batch Processing
+
+Always set `batch: true` (the default) in production. The batch span processor groups spans before export, improving compression and reducing the number of outgoing network requests. Disable batching only during local debugging when you need spans to appear immediately.
+
+```ts
+const provider = register({
+  projectName: "support-bot",
+  url: "https://app.phoenix.arize.com",
+  apiKey: process.env.PHOENIX_API_KEY,
+  batch: true, // default — groups spans for efficient export
+});
+```
+
+### Provider Lifecycle
+
+In production you must flush and shut down the provider before your process exits, otherwise in-flight batches are lost.
+
+```ts
+process.on("SIGTERM", async () => {
+  await provider.shutdown(); // flushes buffered spans, then tears down
+  process.exit(0);
+});
+```
+
+For short-lived processes (scripts, serverless functions, CLI tools) call `shutdown()` at the end of your work:
+
+```ts
+await doWork();
+await provider.shutdown(); // ensures the final batch is exported
+```
+
+### Custom Span Processors
+
+If you need full control over export (for example, sending spans to a secondary backend), pass your own `spanProcessors`. This replaces the default Phoenix exporter setup entirely.
+
+```ts
+import { register } from "@arizeai/phoenix-otel";
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+
+const exporter = new OTLPTraceExporter({
+  url: "https://app.phoenix.arize.com/v1/traces",
+  headers: { Authorization: `Bearer ${process.env.PHOENIX_API_KEY}` },
+});
+
+const provider = register({
+  projectName: "support-bot",
+  spanProcessors: [new BatchSpanProcessor(exporter)],
+});
+```
+
+## Troubleshooting
+
+When traces do not show up in Phoenix, check these common issues:
+
+- confirm `projectName` is the project you are inspecting
+- confirm `url` or `PHOENIX_COLLECTOR_ENDPOINT` points at the collector
+- confirm `PHOENIX_API_KEY` is present for authenticated environments
+- confirm registration happens before the instrumented work starts
+- call `await provider.shutdown()` before process exit when using batched export
+
+### Enable Diagnostic Logging
+
+```ts
+import { DiagLogLevel, register } from "@arizeai/phoenix-otel";
+
+const provider = register({
+  projectName: "support-bot",
+  batch: false,
+  diagLogLevel: DiagLogLevel.DEBUG,
+});
+
+await provider.shutdown();
+```
+
+## Package Surface
+
+- `register()` creates a `NodeTracerProvider` and Phoenix exporter setup
+- `trace`, `SpanStatusCode`, and other OpenTelemetry re-exports support manual tracing
+- `registerInstrumentations()` wires automatic instrumentation into the same provider
+- `objectAsAttributes()` converts JSON-like objects into OpenTelemetry attribute maps
+
+## Where To Start
+
+- [Manual spans](./manual-spans) for tracing with `@arizeai/openinference-core` helpers and raw OTel spans
+
+<section className="hidden" data-agent-context="source-map" aria-label="Source map">
+  <h2>Source Map</h2>
+  <ul>
+    <li><code>src/index.ts</code></li>
+    <li><code>src/register.ts</code></li>
+    <li><code>src/config.ts</code></li>
+    <li><code>src/utils.ts</code></li>
+    <li><code>src/createNoOpProvider.ts</code></li>
+  </ul>
+</section>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arizeai/phoenix-otel",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Otel registration and convenience methods",
   "keywords": [
     "arize",
@@ -19,8 +19,12 @@
     "type": "git",
     "url": "git+https://github.com/Arize-ai/phoenix.git"
   },
+  "directories": {
+    "doc": "./docs"
+  },
   "files": [
     "dist",
+    "docs",
     "src",
     "package.json"
   ],
@@ -37,6 +41,7 @@
     "@arizeai/openinference-semantic-conventions": "^1.1.0",
     "@arizeai/openinference-vercel": "^2.7.0",
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-async-hooks": "^2.5.1",
     "@opentelemetry/core": "^1.25.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.205.0",
     "@opentelemetry/instrumentation": "^0.57.2",
@@ -46,7 +51,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
-    "vitest": "^4.0.10"
+    "vitest": "^4.1.0"
   },
   "scripts": {
     "build": "tsc --build tsconfig.json tsconfig.esm.json && tsc-alias -p tsconfig.esm.json",

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   type Tracer,
   SpanStatusCode,
 } from "@opentelemetry/api";
+export { suppressTracing } from "@opentelemetry/core";
 export { registerInstrumentations } from "@opentelemetry/instrumentation";
 export { type Instrumentation } from "@opentelemetry/instrumentation";
 export { type NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

package/src/register.ts

@@ -4,7 +4,22 @@ import {
   OpenInferenceSimpleSpanProcessor,
 } from "@arizeai/openinference-vercel";
 import type { DiagLogLevel } from "@opentelemetry/api";
-import { diag, DiagConsoleLogger } from "@opentelemetry/api";
+import {
+  context,
+  type ContextManager,
+  diag,
+  DiagConsoleLogger,
+  propagation,
+  type TextMapPropagator,
+  trace,
+  type TracerProvider,
+} from "@opentelemetry/api";
+import { AsyncLocalStorageContextManager } from "@opentelemetry/context-async-hooks";
+import {
+  CompositePropagator,
+  W3CBaggagePropagator,
+  W3CTraceContextPropagator,
+} from "@opentelemetry/core";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
 import type { Instrumentation } from "@opentelemetry/instrumentation";
 import { registerInstrumentations } from "@opentelemetry/instrumentation";
@@ -153,6 +168,214 @@ export type RegisterParams = {
   diagLogLevel?: DiagLogLevel;
 };
 
+export type GlobalTracerProviderRegistration = {
+  /**
+   * Detach the global tracer provider and reset global tracing APIs to no-op state.
+   *
+   * This clears the OpenTelemetry tracer provider, context manager, and propagator
+   * so a different provider can be attached later in the same process.
+   */
+  detach: () => void;
+};
+
+type GlobalTelemetrySnapshot = {
+  contextManager?: ContextManager;
+  propagator?: TextMapPropagator;
+  tracerProvider?: TracerProvider;
+};
+
+type OpenTelemetryGlobalState = {
+  context?: ContextManager;
+  propagation?: TextMapPropagator;
+  trace?: TracerProvider;
+  version?: string;
+};
+
+type GlobalTracerProviderMount = {
+  id: number;
+  provider: NodeTracerProvider;
+};
+
+let nextGlobalTracerProviderMountId = 0;
+let managedGlobalBaseSnapshot: GlobalTelemetrySnapshot | null = null;
+const managedGlobalTracerProviderMounts: GlobalTracerProviderMount[] = [];
+// OpenTelemetry v1 stores globals on this well-known symbol.
+const OTEL_GLOBAL_SYMBOL = Symbol.for("opentelemetry.js.api.1");
+
+function getOpenTelemetryGlobalState(): OpenTelemetryGlobalState | undefined {
+  return (
+    globalThis as typeof globalThis & {
+      [OTEL_GLOBAL_SYMBOL]?: OpenTelemetryGlobalState;
+    }
+  )[OTEL_GLOBAL_SYMBOL];
+}
+
+function getGlobalTelemetrySnapshot(): GlobalTelemetrySnapshot {
+  const globalState = getOpenTelemetryGlobalState();
+
+  return {
+    tracerProvider: globalState?.trace,
+    contextManager: globalState?.context,
+    propagator: globalState?.propagation,
+  };
+}
+
+function clearGlobalTelemetry(): void {
+  trace.disable();
+  context.disable();
+  propagation.disable();
+}
+
+function restoreGlobalTelemetrySnapshot(
+  snapshot: GlobalTelemetrySnapshot | null
+): void {
+  clearGlobalTelemetry();
+
+  if (!snapshot) {
+    return;
+  }
+
+  if (snapshot.tracerProvider) {
+    trace.setGlobalTracerProvider(snapshot.tracerProvider);
+  }
+
+  if (snapshot.contextManager) {
+    context.setGlobalContextManager(snapshot.contextManager);
+  }
+
+  if (snapshot.propagator) {
+    propagation.setGlobalPropagator(snapshot.propagator);
+  }
+}
+
+/**
+ * Sets the given provider as the global OpenTelemetry provider using this
+ * module's own imports of `trace`, `context`, and `propagation`.
+ *
+ * We deliberately avoid calling `provider.register()` because the SDK's
+ * internal import of `@opentelemetry/api` may resolve to a different module
+ * instance in pnpm workspaces (different symlink paths → different module
+ * identity). By routing all global-state mutations through **our** copy of
+ * the OTEL API, snapshot/restore stays consistent.
+ */
+function setGlobalProvider(provider: NodeTracerProvider): void {
+  trace.setGlobalTracerProvider(provider);
+
+  const contextManager = new AsyncLocalStorageContextManager();
+  contextManager.enable();
+  context.setGlobalContextManager(contextManager);
+
+  propagation.setGlobalPropagator(
+    new CompositePropagator({
+      propagators: [
+        new W3CTraceContextPropagator(),
+        new W3CBaggagePropagator(),
+      ],
+    })
+  );
+}
+
+function restorePreviousManagedGlobalTracerProvider(): void {
+  const previousMount =
+    managedGlobalTracerProviderMounts[
+      managedGlobalTracerProviderMounts.length - 1
+    ];
+
+  if (previousMount) {
+    clearGlobalTelemetry();
+    setGlobalProvider(previousMount.provider);
+    return;
+  }
+
+  restoreGlobalTelemetrySnapshot(managedGlobalBaseSnapshot);
+  managedGlobalBaseSnapshot = null;
+}
+
+function detachManagedGlobalTracerProvider(mountId?: number): void {
+  if (managedGlobalTracerProviderMounts.length === 0) {
+    clearGlobalTelemetry();
+    return;
+  }
+
+  const mountIndex =
+    mountId == null
+      ? managedGlobalTracerProviderMounts.length - 1
+      : managedGlobalTracerProviderMounts.findIndex(
+          (mount) => mount.id === mountId
+        );
+
+  if (mountIndex === -1) {
+    return;
+  }
+
+  const isTopMount =
+    mountIndex === managedGlobalTracerProviderMounts.length - 1;
+  managedGlobalTracerProviderMounts.splice(mountIndex, 1);
+
+  if (!isTopMount) {
+    return;
+  }
+
+  restorePreviousManagedGlobalTracerProvider();
+}
+
+/**
+ * Detaches the current global OpenTelemetry tracer provider and resets the
+ * global trace, context, and propagation APIs.
+ */
+export function detachGlobalTracerProvider(): void {
+  detachManagedGlobalTracerProvider();
+}
+
+/**
+ * Attaches an existing tracer provider as the global OpenTelemetry provider.
+ *
+ * Returns a handle that can be used to detach it later so another provider can
+ * be attached in the same process.
+ */
+export function attachGlobalTracerProvider(
+  provider: NodeTracerProvider
+): GlobalTracerProviderRegistration {
+  if (managedGlobalTracerProviderMounts.length === 0) {
+    managedGlobalBaseSnapshot = getGlobalTelemetrySnapshot();
+  }
+
+  const mountId = nextGlobalTracerProviderMountId++;
+  managedGlobalTracerProviderMounts.push({
+    id: mountId,
+    provider,
+  });
+
+  clearGlobalTelemetry();
+  setGlobalProvider(provider);
+
+  return {
+    detach: () => {
+      detachManagedGlobalTracerProvider(mountId);
+    },
+  };
+}
+
+function bindGlobalTracerProviderRegistrationToShutdown({
+  provider,
+  registration,
+}: {
+  provider: NodeTracerProvider;
+  registration: GlobalTracerProviderRegistration;
+}): void {
+  const shutdown = provider.shutdown.bind(provider);
+  let hasDetachedRegistration = false;
+
+  provider.shutdown = async (): Promise<void> => {
+    if (!hasDetachedRegistration) {
+      hasDetachedRegistration = true;
+      registration.detach();
+    }
+
+    await shutdown();
+  };
+}
+
 /**
  * Registers Phoenix OpenTelemetry tracing with the specified configuration.
  *
@@ -261,7 +484,11 @@ export function register(params: RegisterParams): NodeTracerProvider {
     });
   }
   if (global) {
-    provider.register();
+    const registration = attachGlobalTracerProvider(provider);
+    bindGlobalTracerProviderRegistrationToShutdown({
+      provider,
+      registration,
+    });
   }
   return provider;
 }