# @arizeai/openinference-vercel

**JavaScript · Integration**

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`

[npm](https://www.npmjs.com/package/@arizeai/openinference-vercel) · [README](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/README.md) · [Source](https://github.com/Arize-ai/openinference/tree/main/js/packages/openinference-vercel)

## Install

```sh
npm install @arizeai/openinference-vercel
```

## `@arizeai/openinference-vercel`

### `OpenInferenceSimpleSpanProcessor`

_class_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L37)

```typescript
class OpenInferenceSimpleSpanProcessor extends SimpleSpanProcessor
```

Extends [SimpleSpanProcessor](https://opentelemetry.io/docs/instrumentation/js/manual/#simple-span-processor) 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**

```typescript
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`

_constructor_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L43)

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

**Parameters**

| 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 `spanFilter` drops non-OpenInference spans (e.g. [`isOpenInferenceSpan`](https://openinf.dev/js/openinference-vercel.html.md#utils/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?` | `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 `@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`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L110)

```typescript
onStart(span: Span, parentContext: Context): void
```

#### `onEnd`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L121)

```typescript
onEnd(span: ReadableSpan): void
```

#### `shutdown`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L140)

```typescript
shutdown(): Promise<void>
```

#### `forceFlush`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L145)

```typescript
forceFlush(): Promise<void>
```

### `OpenInferenceBatchSpanProcessor`

_class_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L178)

```typescript
class OpenInferenceBatchSpanProcessor extends BatchSpanProcessor
```

Extends [BatchSpanProcessor](https://opentelemetry.io/docs/instrumentation/js/manual/#batch-span-processor) 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**

```typescript
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`

_constructor_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L184)

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

**Parameters**

| 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 `spanFilter` drops non-OpenInference spans (e.g. [`isOpenInferenceSpan`](https://openinf.dev/js/openinference-vercel.html.md#utils/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?` | `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 `@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`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L254)

```typescript
onStart(span: Span, parentContext: Context): void
```

#### `onEnd`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L265)

```typescript
onEnd(span: ReadableSpan): void
```

#### `shutdown`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L284)

```typescript
shutdown(): Promise<void>
```

#### `forceFlush`

_method_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/OpenInferenceSpanProcessor.ts#L289)

```typescript
forceFlush(): Promise<void>
```

### `enrichSpanWithOpenInference`

_constant_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/enrichSpan.ts#L35)

```typescript
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**

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

### `SpanFilter`

_re-export_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/index.ts#L3)

Re-exports [`types.SpanFilter`](https://openinf.dev/js/openinference-vercel.html.md#types/SpanFilter).

### `isOpenInferenceSpan`

_re-export_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/index.ts#L4)

Re-exports [`utils.isOpenInferenceSpan`](https://openinf.dev/js/openinference-vercel.html.md#utils/isOpenInferenceSpan).

## `@arizeai/openinference-vercel/utils`

### `safelyGetOpenInferenceAttributes`

_constant_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/utils.ts#L1536)

```typescript
const safelyGetOpenInferenceAttributes: SafeFunction<(attributes: Attributes) => Attributes>
```

`getOpenInferenceAttributes` wrapped in [`withSafety`](https://openinf.dev/js/openinference-core.html.md#withSafety) which will return null if any error is thrown

### `isOpenInferenceSpan`

_function_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/utils.ts#L1541)

```typescript
function isOpenInferenceSpan(span: ReadableSpan): boolean
```

### `shouldExportSpan`

_function_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/utils.ts#L1553)

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

Determines 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`

_function_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/utils.ts#L1590)

```typescript
function addOpenInferenceAttributesToSpan(span: ReadableSpan): void
```

Adds 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 alias_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/types.ts#L13)

```typescript
type ReadWriteSpan = Mutable<ReadableSpan>
```

A ReadWriteSpan is a mutable [ReadableSpan](https://opentelemetry.io/docs/specs/otel/trace/sdk/#additional-span-interfaces). 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

> **See also**
>
> <https://github.com/open-telemetry/opentelemetry-specification/pull/4024> We use this type to directly mutate the attributes of spans in the OpenInferenceSpanProcessor

### `OpenInferenceSemanticConventionKey`

_type alias_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/types.ts#L15)

```typescript
type OpenInferenceSemanticConventionKey = ValueOf<typeof SemanticConventions>
```

### `OpenInferenceIOConventionKey`

_type alias_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/types.ts#L17)

```typescript
type OpenInferenceIOConventionKey = Extract<OpenInferenceSemanticConventionKey, typeof SemanticConventions.OUTPUT_VALUE | typeof SemanticConventions.INPUT_VALUE>
```

### `SpanFilter`

_type alias_ · [Source](https://github.com/Arize-ai/openinference/blob/main/js/packages/openinference-vercel/src/types.ts#L25)

```typescript
type SpanFilter = (span: ReadableSpan) => boolean
```

A filter to apply to a [ReadableSpan](https://opentelemetry.io/docs/specs/otel/trace/sdk/#additional-span-interfaces).
