JavaScript APIopeninference-vercel

Core

Instrumentation

Integrations

JavaScript · Integration

@arizeai/openinference-vercel

OpenInference utilities for ingesting Vercel AI SDK spans

Version
3.3.4
Node.js
>=22
Peer dependencies
@ai-sdk/otel ^1.0.0, @opentelemetry/api >=1.7.0 <2.0.0, @opentelemetry/semantic-conventions >=1.41.1 <2.0.0, ai ^7.0.0

Install

npm install @arizeai/openinference-vercel

@arizeai/openinference-vercel

OpenInferenceSimpleSpanProcessor

classSource ↗
class OpenInferenceSimpleSpanProcessor extends SimpleSpanProcessor

Extends SimpleSpanProcessor to support OpenInference attributes. This processor enhances spans with OpenInference attributes before exporting them. It can be configured to selectively export only OpenInference spans or all spans.

Examples

import { OpenInferenceSimpleSpanProcessor, isOpenInferenceSpan } from "@arizeai/openinference-vercel";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto"

const exporter = new OTLPTraceExporter();
const processor = new OpenInferenceSimpleSpanProcessor({
  exporter,
  spanFilter: isOpenInferenceSpan,
});

const tracerProvider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [SEMRESATTRS_PROJECT_NAME]: "your-project-name",
  }),
  spanProcessors: [processor], // <-- pass processor here
});

new OpenInferenceSimpleSpanProcessor

constructorSource ↗
new OpenInferenceSimpleSpanProcessor(
  options: {
    exporter: SpanExporter;
    spanFilter?: SpanFilter;
    reparentOrphanedSpans?: boolean;
    propagateContextAttributes?: boolean;
    config?: BufferConfig;
  },
): OpenInferenceSimpleSpanProcessor

Parameters

NameTypeDefaultDescription
exporterSpanExporter

The exporter to pass spans to.

spanFilter?SpanFilter

A filter to apply to spans before exporting. If it returns true for a given span, that span will be exported.

reparentOrphanedSpans?booleanfalse

Reparents AI spans that would be orphaned by span filtering. When a spanFilter drops non-OpenInference spans (e.g. isOpenInferenceSpan), the highest-level AI span (e.g. ai.generateText, ai.streamText) is often parented under a non-AI span — such as the HTTP/server span Next.js parents everything under — which the filter removes, leaving the AI span pointing at a parent that was never exported.

When enabled, any AI span whose direct parent is a non-AI span is detached (re-rooted) so it becomes a trace root. Handles multiple sibling AI spans per trace; AI spans nested under an AI parent are left intact. The check is stateless — the parent span is read from the start-time context.

If a re-rooted root is an AI-like span the kind map doesn’t recognize (e.g. a framework “turn”/wrapper span), it would otherwise be kind-less and dropped by the filter; it is tagged openinference.span.kind = AGENT so it is kept as the trace root. Recognized spans keep the kind the map gave them (e.g. ai.embed stays CHAIN); only kind-less AI-like roots get the AGENT fallback.

Intended for use alongside a filter that drops non-AI parent spans — without such a filter the non-AI parent is still exported and reparenting would split the trace.

propagateContextAttributes?booleantrue

Copies OpenInference context attributes onto each span at start time.

The Vercel AI SDK creates its own spans, so this processor never reads the OpenInference context the way the OpenInference instrumentors do. As a result, values set with the @arizeai/openinference-core helpers — setSession, setUser, setMetadata, setTags — never reach the exported AI spans.

When enabled, every OpenInference attribute (session.id, user.id, metadata.*, tag.tags, …) present on the start-time context is written directly onto the span, so e.g. a session.id set via context.with(setSession(context.active(), { sessionId }), () => streamText(...)) groups the trace into a session in Arize / Phoenix. Setting them at start time means children started in the same context inherit them, and the values survive reparentOrphanedSpans and export.

config?BufferConfig

onStart

methodSource ↗
onStart(span: Span, parentContext: Context): void

onEnd

methodSource ↗
onEnd(span: ReadableSpan): void

shutdown

methodSource ↗
shutdown(): Promise<void>

forceFlush

methodSource ↗
forceFlush(): Promise<void>

OpenInferenceBatchSpanProcessor

classSource ↗
class OpenInferenceBatchSpanProcessor extends BatchSpanProcessor

Extends BatchSpanProcessor to support OpenInference attributes. This processor enhances spans with OpenInference attributes before exporting them. It can be configured to selectively export only OpenInference spans or all spans.

Examples

import { OpenInferenceBatchSpanProcessor, isOpenInferenceSpan } from "@arizeai/openinference-vercel";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto"

const exporter = new OTLPTraceExporter();
const processor = new OpenInferenceBatchSpanProcessor({
  exporter,
  spanFilter: isOpenInferenceSpan,
  config: { maxQueueSize: 2048, scheduledDelayMillis: 5000 },
});

const tracerProvider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [SEMRESATTRS_PROJECT_NAME]: "your-project-name",
  }),
  spanProcessors: [processor], // <-- pass processor here
});

new OpenInferenceBatchSpanProcessor

constructorSource ↗
new OpenInferenceBatchSpanProcessor(
  options: {
    exporter: SpanExporter;
    spanFilter?: SpanFilter;
    reparentOrphanedSpans?: boolean;
    propagateContextAttributes?: boolean;
    config?: BufferConfig;
  },
): OpenInferenceBatchSpanProcessor

Parameters

NameTypeDefaultDescription
exporterSpanExporter

The exporter to pass spans to.

spanFilter?SpanFilter

A filter to apply to spans before exporting. If it returns true for a given span, that span will be exported.

reparentOrphanedSpans?booleanfalse

Reparents AI spans that would be orphaned by span filtering. When a spanFilter drops non-OpenInference spans (e.g. isOpenInferenceSpan), the highest-level AI span (e.g. ai.generateText, ai.streamText) is often parented under a non-AI span — such as the HTTP/server span Next.js parents everything under — which the filter removes, leaving the AI span pointing at a parent that was never exported.

When enabled, any AI span whose direct parent is a non-AI span is detached (re-rooted) so it becomes a trace root. Handles multiple sibling AI spans per trace; AI spans nested under an AI parent are left intact. The check is stateless — the parent span is read from the start-time context.

If a re-rooted root is an AI-like span the kind map doesn’t recognize (e.g. a framework “turn”/wrapper span), it would otherwise be kind-less and dropped by the filter; it is tagged openinference.span.kind = AGENT so it is kept as the trace root. Recognized spans keep the kind the map gave them (e.g. ai.embed stays CHAIN); only kind-less AI-like roots get the AGENT fallback.

Intended for use alongside a filter that drops non-AI parent spans — without such a filter the non-AI parent is still exported and reparenting would split the trace.

propagateContextAttributes?booleantrue

Copies OpenInference context attributes onto each span at start time.

The Vercel AI SDK creates its own spans, so this processor never reads the OpenInference context the way the OpenInference instrumentors do. As a result, values set with the @arizeai/openinference-core helpers — setSession, setUser, setMetadata, setTags — never reach the exported AI spans.

When enabled, every OpenInference attribute (session.id, user.id, metadata.*, tag.tags, …) present on the start-time context is written directly onto the span, so e.g. a session.id set via context.with(setSession(context.active(), { sessionId }), () => streamText(...)) groups the trace into a session in Arize / Phoenix. Setting them at start time means children started in the same context inherit them, and the values survive reparentOrphanedSpans and export.

config?BufferConfig

The configuration options for processor.

onStart

methodSource ↗
onStart(span: Span, parentContext: Context): void

onEnd

methodSource ↗
onEnd(span: ReadableSpan): void

shutdown

methodSource ↗
shutdown(): Promise<void>

forceFlush

methodSource ↗
forceFlush(): Promise<void>

enrichSpanWithOpenInference

constantSource ↗
const enrichSpanWithOpenInference: EnrichSpan

Provides OpenInference attributes when @ai-sdk/otel creates a span.

Pass this callback as OpenTelemetry’s enrichSpan option alongside an OpenInference span processor. It uses the SDK’s span type and operation ID when the emitted GenAI attributes do not distinguish the span’s role. For decision calls, it marks the outer operation as CHAIN and the model call as DECISION. Other spans are left to the processor’s normal mapping.

Requires ai 7.0.128 and @ai-sdk/otel 1.0.128 or later.

Examples

registerTelemetry(
  new OpenTelemetry({ enrichSpan: enrichSpanWithOpenInference }),
);

SpanFilter

re-exportSource ↗

Re-exports types.SpanFilter.

isOpenInferenceSpan

re-exportSource ↗

Re-exports utils.isOpenInferenceSpan.

@arizeai/openinference-vercel/utils

safelyGetOpenInferenceAttributes

constantSource ↗
const safelyGetOpenInferenceAttributes: SafeFunction<(attributes: Attributes) => Attributes>

getOpenInferenceAttributes wrapped in withSafety which will return null if any error is thrown

isOpenInferenceSpan

functionSource ↗
function isOpenInferenceSpan(span: ReadableSpan): boolean

shouldExportSpan

functionSource ↗
function shouldExportSpan(
  params: { span: ReadableSpan; spanFilter?: SpanFilter },
): boolean

Determines whether a span should be exported based on configuration and the spans attributes.

Parameters

NameTypeDescription
params{ span: ReadableSpan; spanFilter?: SpanFilter }

The parameters object

params.spanReadableSpan

The span to check for export eligibility

params.spanFilter?SpanFilter

A filter to apply to a span before exporting. If it returns true for a given span, the span will be exported

Returns

TypeDescription
boolean

true if the span should be exported, false otherwise.

addOpenInferenceAttributesToSpan

functionSource ↗
function addOpenInferenceAttributesToSpan(span: ReadableSpan): void

Adds OpenInference attributes to a span based on the span’s existing attributes.

Parameters

NameTypeDescription
spanReadableSpan

The span to add OpenInference attributes to.

@arizeai/openinference-vercel/types

ReadWriteSpan

type aliasSource ↗
type ReadWriteSpan = Mutable<ReadableSpan>

A ReadWriteSpan is a mutable ReadableSpan. Within the OpenTelemetry SpanProcessors, the spans are typed as readonly However, mutation of spans in processors has been added to the OTEL spec and implementation is in progress

OpenInferenceSemanticConventionKey

type aliasSource ↗
type OpenInferenceSemanticConventionKey = ValueOf<typeof SemanticConventions>

OpenInferenceIOConventionKey

type aliasSource ↗
type OpenInferenceIOConventionKey = Extract<OpenInferenceSemanticConventionKey, typeof SemanticConventions.OUTPUT_VALUE | typeof SemanticConventions.INPUT_VALUE>

SpanFilter

type aliasSource ↗
type SpanFilter = (span: ReadableSpan) => boolean

A filter to apply to a ReadableSpan.