Tracing Helpers

@arizeai/phoenix-otel re-exports the OpenInference tracing helpers from @arizeai/openinference-core, so you can configure Phoenix export and author traced functions from one package path.

npm install @arizeai/phoenix-otel

import { register, traceChain, traceTool } from "@arizeai/phoenix-otel";register({ projectName: "my-app" });const fetchWeather = traceTool(  async (city: string) => ({ city, temp: 72 }),  { name: "fetch-weather" });const handleQuery = traceChain(  async (query: string) => {    const weather = await fetchWeather("San Francisco");    return `It is ${weather.temp}F in ${weather.city}`;  },  { name: "handle-query" });await handleQuery("What's the weather?");

Why These Re-Exports Matter#

@arizeai/phoenix-otel adds Phoenix registration and export. The tracing helpers themselves come from @arizeai/openinference-core.

Those helpers resolve the default tracer when the wrapped function is invoked, not when the wrapper is created. That means:

functions wrapped at module load continue following later global provider changes
experiment-scoped providers still receive spans from previously defined helpers
you can keep using the same wrappers when moving between standalone tracing and experiment workflows

API Reference#

`withSpan(fn, options?)`#

The general-purpose wrapper. All other helper wrappers build on it.

import { OpenInferenceSpanKind, withSpan } from "@arizeai/phoenix-otel";const retrieveDocs = withSpan(  async (query: string) => {    return [`Document for ${query}`];  },  {    name: "retrieve-docs",    kind: OpenInferenceSpanKind.RETRIEVER,  });

Options (SpanTraceOptions):

Field	Type	Default	Description
`name`	`string`	`fn.name`	Span name. Falls back to the function name.
`kind`	`OpenInferenceSpanKind`	`CHAIN`	OpenInference span kind such as `CHAIN`, `AGENT`, `TOOL`, `LLM`, or `RETRIEVER`.
`tracer`	`Tracer`	default tracer	Override the tracer instance. When omitted, the default tracer is resolved when the wrapper runs.
`attributes`	`Attributes`	—	Base attributes merged into every span.
`processInput`	`(...args) => Attributes`	`defaultProcessInput`	Custom function to extract span attributes from input arguments.
`processOutput`	`(result) => Attributes`	`defaultProcessOutput`	Custom function to extract span attributes from the return value.
`openTelemetrySpanKind`	`SpanKind`	`SpanKind.INTERNAL`	Underlying OpenTelemetry span kind.

Behavior:

wraps both sync and async functions
records input and output attributes automatically
records exceptions, marks the span as ERROR, closes the span, and re-throws
preserves the call-time this value

`traceChain(fn, options?)`#

Shorthand for withSpan(fn, { ...options, kind: OpenInferenceSpanKind.CHAIN }).

import { traceChain } from "@arizeai/phoenix-otel";const summarize = traceChain(  async (text: string) => {    return `Summary of ${text.length} chars`;  },  { name: "summarize" });

`traceAgent(fn, options?)`#

Shorthand for withSpan(fn, { ...options, kind: OpenInferenceSpanKind.AGENT }).

import { traceAgent } from "@arizeai/phoenix-otel";const supportAgent = traceAgent(  async (question: string) => {    return { answer: `Working on: ${question}` };  },  { name: "support-agent" });

`traceTool(fn, options?)`#

Shorthand for withSpan(fn, { ...options, kind: OpenInferenceSpanKind.TOOL }).

import { traceTool } from "@arizeai/phoenix-otel";const searchDocs = traceTool(  async (query: string) => {    const response = await fetch(`/api/search?q=${query}`);    return response.json();  },  { name: "search-docs" });

Additional Span-Kind Wrappers#

Alongside traceChain, traceAgent, and traceTool, the following wrappers cover the remaining OpenInference span kinds. Each is a shorthand for withSpan(fn, { ...options, kind }) with the listed span kind pre-configured, accepts the same SpanTraceOptions (minus kind), and resolves the default tracer at invocation time.

Note

These wrappers are marked @experimental in @arizeai/openinference-core and may change in a future release.

Wrapper	Span kind	Use it for
`traceLLM(fn, options?)`	`LLM`	Invocations of a large language model — chat or text completions and other foundation-model inference calls.
`traceRetriever(fn, options?)`	`RETRIEVER`	Fetching documents or context from a knowledge base, vector store, or search index (RAG).
`traceReranker(fn, options?)`	`RERANKER`	Reordering or scoring candidate documents by relevance before passing them to a model.
`traceEmbedding(fn, options?)`	`EMBEDDING`	Converting text or other data into vector representations for semantic search and retrieval.
`traceGuardrail(fn, options?)`	`GUARDRAIL`	Safety, validation, or policy checks such as content moderation, PII detection, or compliance enforcement.
`traceEvaluator(fn, options?)`	`EVALUATOR`	Assessing or scoring output quality — relevance scoring, correctness checks, or LLM-as-a-judge evaluations.
`tracePrompt(fn, options?)`	`PROMPT`	Constructing, rendering, or templating a prompt before it is sent to a model.

import {  traceEmbedding,  traceEvaluator,  traceGuardrail,  traceLLM,  tracePrompt,  traceReranker,  traceRetriever,} from "@arizeai/phoenix-otel";// traceRetriever — fetch context from a vector storeconst retrieveDocuments = traceRetriever(  async (query: string) => vectorStore.similaritySearch(query, 5),  { name: "vector-search" });// traceReranker — reorder candidates by relevanceconst rerankDocuments = traceReranker(  async (query: string, documents: Document[]) =>    reranker.rerank(query, documents),  { name: "rerank" });// traceEmbedding — turn text into vectorsconst embedText = traceEmbedding(  async (text: string) =>    client.embeddings.create({ model: "text-embedding-3-small", input: text }),  { name: "embed-text" });// tracePrompt — render a prompt templateconst renderPrompt = tracePrompt(  (variables: Record<string, string>) => promptTemplate.format(variables),  { name: "render-prompt" });// traceLLM — call a language modelconst chatCompletion = traceLLM(  async (messages: Message[]) =>    client.chat.completions.create({ model: "gpt-4", messages }),  { name: "chat-completion" });// traceGuardrail — moderate or validate contentconst moderateContent = traceGuardrail(  async (text: string) => moderationClient.check(text),  { name: "content-moderation" });// traceEvaluator — score an answer (e.g. LLM-as-a-judge)const evaluateAnswer = traceEvaluator(  async (question: string, answer: string) => judge.score({ question, answer }),  { name: "answer-evaluation" });

`observe(options?)`#

Decorator factory for class methods. Use TypeScript 5+ standard decorators.

import { OpenInferenceSpanKind, observe } from "@arizeai/phoenix-otel";class SupportBot {  @observe({ kind: OpenInferenceSpanKind.AGENT })  async handleTicket(ticketId: string) {    return { resolved: true, ticketId };  }  @observe({ kind: OpenInferenceSpanKind.TOOL, name: "lookup-customer" })  async lookupCustomer(customerId: string) {    return { customerId, name: "Alice" };  }}

observe preserves method this context and uses the method name as the default span name unless you pass name.

Input / Output Processing#

By default, withSpan serializes function arguments into input.value and the return value into output.value. Override this with processInput and processOutput when you want richer OpenInference attributes.

import {  OpenInferenceSpanKind,  getInputAttributes,  getRetrieverAttributes,  withSpan,} from "@arizeai/phoenix-otel";const retriever = withSpan(  async (query: string) => [`Doc A for ${query}`, `Doc B for ${query}`],  {    name: "retriever",    kind: OpenInferenceSpanKind.RETRIEVER,    processInput: (query) => getInputAttributes(query),    processOutput: (documents) =>      getRetrieverAttributes({        documents: documents.map((content, index) => ({          id: `doc-${index}`,          content,        })),      }),  });

The same customization pattern works with every span-kind wrapper (traceChain, traceAgent, traceTool, traceLLM, traceRetriever, traceReranker, traceEmbedding, traceGuardrail, traceEvaluator, and tracePrompt), since they all delegate to withSpan.

Combining Helpers With Context Attributes#

Tracing helpers compose naturally with context attributes. Wrap a call in context.with() to propagate session IDs, metadata, or tags to all child spans.

import {  context,  register,  setMetadata,  setSession,  traceAgent,  traceTool,} from "@arizeai/phoenix-otel";register({ projectName: "support-bot" });const searchKB = traceTool(  async (query: string) => [{ title: "Password Reset", body: "..." }],  { name: "search-kb" });const supportAgent = traceAgent(  async (question: string) => {    const docs = await searchKB(question);    return `Based on ${docs.length} articles: ...`;  },  { name: "support-agent" });await context.with(  setMetadata(    setSession(context.active(), { sessionId: "sess-abc-123" }),    { environment: "production", region: "us-east-1" }  ),  () => supportAgent("How do I reset my password?"));

Use With Experiments#

When you run experiments with @arizeai/phoenix-client, the experiment framework can attach a per-run global provider. Because the wrappers resolve the default tracer at invocation time, traced functions defined at module scope still route spans to the active provider.

import { traceTool } from "@arizeai/phoenix-otel";import { createClient } from "@arizeai/phoenix-client";import {  asExperimentEvaluator,  runExperiment,} from "@arizeai/phoenix-client/experiments";const classifyIntent = traceTool(  async (text: string) => ({ intent: "billing", confidence: 0.95 }),  { name: "classify-intent" });const client = createClient();await runExperiment({  client,  datasetId: "my-dataset",  task: async (example) => classifyIntent(example.input.text as string),  evaluators: [    asExperimentEvaluator({      name: "contains-intent",      evaluate: async ({ output }) => output.intent === "billing",    }),  ],});

Tracing Helpers

Relevant Source Files

Why These Re-Exports Matter#

API Reference#

`withSpan(fn, options?)`#

`traceChain(fn, options?)`#

`traceAgent(fn, options?)`#

`traceTool(fn, options?)`#

Additional Span-Kind Wrappers#

`observe(options?)`#

Input / Output Processing#

Combining Helpers With Context Attributes#

Use With Experiments#

Source Map

Relevant Source Files

Why These Re-Exports Matter#

API Reference#

withSpan(fn, options?)#

traceChain(fn, options?)#

traceAgent(fn, options?)#

traceTool(fn, options?)#

Additional Span-Kind Wrappers#

observe(options?)#

Input / Output Processing#

Combining Helpers With Context Attributes#

Use With Experiments#

Source Map

`withSpan(fn, options?)`#

`traceChain(fn, options?)`#

`traceAgent(fn, options?)`#

`traceTool(fn, options?)`#

`observe(options?)`#