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 SimpleSpanProcessorExtends 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;
},
): OpenInferenceSimpleSpanProcessorParameters
| Name | Type | Default | Description |
|---|---|---|---|
exporter | SpanExporter | 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? | boolean | false | Reparents AI spans that would be orphaned by span filtering. When a 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 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? | boolean | true | 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 When enabled, every OpenInference attribute ( |
config? | BufferConfig |
onStart
methodSource ↗onStart(span: Span, parentContext: Context): voidonEnd
methodSource ↗onEnd(span: ReadableSpan): voidshutdown
methodSource ↗shutdown(): Promise<void>forceFlush
methodSource ↗forceFlush(): Promise<void>OpenInferenceBatchSpanProcessor
classSource ↗class OpenInferenceBatchSpanProcessor extends BatchSpanProcessorExtends 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;
},
): OpenInferenceBatchSpanProcessorParameters
| Name | Type | Default | Description |
|---|---|---|---|
exporter | SpanExporter | 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? | boolean | false | Reparents AI spans that would be orphaned by span filtering. When a 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 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? | boolean | true | 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 When enabled, every OpenInference attribute ( |
config? | BufferConfig | The configuration options for processor. |
onStart
methodSource ↗onStart(span: Span, parentContext: Context): voidonEnd
methodSource ↗onEnd(span: ReadableSpan): voidshutdown
methodSource ↗shutdown(): Promise<void>forceFlush
methodSource ↗forceFlush(): Promise<void>enrichSpanWithOpenInference
constantSource ↗const enrichSpanWithOpenInference: EnrichSpanProvides 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): booleanshouldExportSpan
functionSource ↗function shouldExportSpan(
params: { span: ReadableSpan; spanFilter?: SpanFilter },
): booleanDetermines whether a span should be exported based on configuration and the spans attributes.
Parameters
| Name | Type | Description |
|---|---|---|
params | { span: ReadableSpan; spanFilter?: SpanFilter } | The parameters object |
params.span | ReadableSpan | 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
| Type | Description |
|---|---|
boolean | true if the span should be exported, false otherwise. |
addOpenInferenceAttributesToSpan
functionSource ↗function addOpenInferenceAttributesToSpan(span: ReadableSpan): voidAdds OpenInference attributes to a span based on the span’s existing attributes.
Parameters
| Name | Type | Description |
|---|---|---|
span | ReadableSpan | 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) => booleanA filter to apply to a ReadableSpan.