@ai-sdk/otel 1.0.0-canary.98 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/otel",
-  "version": "1.0.0-canary.98",
+  "version": "1.0.0",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -27,15 +27,16 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
-    "@ai-sdk/provider": "4.0.0-canary.17",
-    "ai": "7.0.0-canary.152"
+    "ai": "7.0.0",
+    "@ai-sdk/provider": "4.0.0"
   },
   "devDependencies": {
+    "@opentelemetry/sdk-trace-base": "2.7.1",
     "@types/node": "22.19.19",
     "tsup": "^8.5.1",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/provider-utils": "5.0.0-canary.43",
+    "@ai-sdk/provider-utils": "5.0.0",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "engines": {

package/src/get-base-telemetry-attributes.ts

@@ -1,5 +1,6 @@
 import type { Attributes, AttributeValue } from '@opentelemetry/api';
 import type { LanguageModelCallOptions } from 'ai';
+import { getRuntimeContextAttributes } from './supplemental-attributes';
 
 export function getBaseTelemetryAttributes({
   model,
@@ -23,12 +24,7 @@ export function getBaseTelemetryAttributes({
     }, {} as Attributes),
 
     // add context as attributes:
-    ...Object.entries(context ?? {}).reduce((attributes, [key, value]) => {
-      if (value != undefined) {
-        attributes[`ai.settings.context.${key}`] = value as AttributeValue;
-      }
-      return attributes;
-    }, {} as Attributes),
+    ...(getRuntimeContextAttributes(context) as Attributes),
 
     // request headers
     ...Object.entries(headers ?? {}).reduce((attributes, [key, value]) => {

package/src/legacy-open-telemetry.ts

@@ -19,13 +19,14 @@ import type {
   GenerateObjectStartEvent,
   GenerateObjectStepEndEvent,
   GenerateObjectStepStartEvent,
+  GenerateTextAbortEvent,
   GenerateTextEndEvent,
   GenerateTextStartEvent,
   GenerateTextStepEndEvent,
   GenerateTextStepStartEvent,
   ToolExecutionEndEvent,
   ToolExecutionStartEvent,
-  OutputInterface as Output,
+  Output,
   RerankingModelCallEndEvent,
   RerankEndEvent,
   RerankStartEvent,
@@ -37,6 +38,7 @@ import type {
 } from 'ai';
 import { assembleOperationName } from './assemble-operation-name';
 import { getBaseTelemetryAttributes } from './get-base-telemetry-attributes';
+import { sanitizeAttributeValue } from './sanitize-attribute-value';
 import { stringifyForTelemetry } from './stringify-for-telemetry';
 
 function recordSpanError(span: Span, error: unknown): void {
@@ -87,7 +89,10 @@ function selectAttributes(
     ) {
       if (telemetry?.recordInputs === false) continue;
       const resolved = value.input();
-      if (resolved != null) result[key] = resolved;
+      if (resolved != null) {
+        const sanitized = sanitizeAttributeValue(resolved);
+        if (sanitized != null) result[key] = sanitized;
+      }
       continue;
     }
 
@@ -98,11 +103,15 @@ function selectAttributes(
     ) {
       if (telemetry?.recordOutputs === false) continue;
       const resolved = value.output();
-      if (resolved != null) result[key] = resolved;
+      if (resolved != null) {
+        const sanitized = sanitizeAttributeValue(resolved);
+        if (sanitized != null) result[key] = sanitized;
+      }
       continue;
     }
 
-    result[key] = value as AttributeValue;
+    const sanitized = sanitizeAttributeValue(value as AttributeValue);
+    if (sanitized != null) result[key] = sanitized;
   }
 
   return result;
@@ -111,7 +120,7 @@ function selectAttributes(
 interface OtelStepStartEvent<
   TOOLS extends ToolSet = ToolSet,
   RUNTIME_CONTEXT extends AISDKContext = AISDKContext,
-  OUTPUT extends Output = Output,
+  OUTPUT extends Output.Output = Output.Output,
 > extends GenerateTextStepStartEvent<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
   readonly promptMessages?: LanguageModelV4Prompt;
   readonly stepTools?: ReadonlyArray<Record<string, unknown>>;
@@ -174,6 +183,26 @@ export class LegacyOpenTelemetry implements Telemetry {
     return context.with(toolSpanEntry.context, execute);
   }
 
+  /**
+   * Runs the provider `doGenerate`/`doStream` call with the active legacy
+   * model-call context.
+   */
+  executeLanguageModelCall<T>({
+    callId,
+    execute,
+  }: {
+    callId: string;
+    execute: () => PromiseLike<T>;
+  }): PromiseLike<T> {
+    const stepContext = this.getCallState(callId)?.stepContext;
+
+    if (stepContext == null) {
+      return execute();
+    }
+
+    return context.with(stepContext, execute);
+  }
+
   onStart(
     event:
       | InferTelemetryEvent<GenerateTextStartEvent>
@@ -391,7 +420,7 @@ export class LegacyOpenTelemetry implements Telemetry {
   }
 
   /** @deprecated */
-  onObjectStepFinish(event: GenerateObjectStepEndEvent): void {
+  onObjectStepEnd(event: GenerateObjectStepEndEvent): void {
     const state = this.getCallState(event.callId);
     if (!state?.stepSpan) return;
 
@@ -634,7 +663,7 @@ export class LegacyOpenTelemetry implements Telemetry {
     state.toolSpans.delete(event.toolCall.toolCallId);
   }
 
-  onStepFinish(event: GenerateTextStepEndEvent<ToolSet>): void {
+  onStepEnd(event: GenerateTextStepEndEvent<ToolSet>): void {
     const state = this.getCallState(event.callId);
     if (!state?.stepSpan) return;
 
@@ -687,7 +716,7 @@ export class LegacyOpenTelemetry implements Telemetry {
           ? JSON.stringify(event.providerMetadata)
           : undefined,
         'ai.response.msToFirstChunk': isStreamText
-          ? event.performance.timeToFirstOutputTokenMs
+          ? event.performance.timeToFirstOutputMs
           : undefined,
         'ai.response.msToFinish': isStreamText
           ? event.performance.responseTimeMs
@@ -722,10 +751,9 @@ export class LegacyOpenTelemetry implements Telemetry {
       }),
     );
 
-    if (isStreamText && event.performance.timeToFirstOutputTokenMs != null) {
+    if (isStreamText && event.performance.timeToFirstOutputMs != null) {
       state.stepSpan.addEvent('ai.stream.firstChunk', {
-        'ai.response.msToFirstChunk':
-          event.performance.timeToFirstOutputTokenMs,
+        'ai.response.msToFirstChunk': event.performance.timeToFirstOutputMs,
       });
     }
 
@@ -742,6 +770,11 @@ export class LegacyOpenTelemetry implements Telemetry {
     state.stepContext = undefined;
   }
 
+  /** @deprecated Use `onStepEnd` instead. */
+  onStepFinish(event: GenerateTextStepEndEvent<ToolSet>): void {
+    this.onStepEnd(event);
+  }
+
   onEnd(
     event:
       | GenerateTextEndEvent<ToolSet>
@@ -790,8 +823,8 @@ export class LegacyOpenTelemetry implements Telemetry {
         },
         'ai.response.reasoning': {
           output: () =>
-            event.reasoning.length > 0
-              ? event.reasoning
+            event.finalStep.reasoning.length > 0
+              ? event.finalStep.reasoning
                   .filter(part => 'text' in part)
                   .map(part => part.text)
                   .join('\n')
@@ -821,27 +854,27 @@ export class LegacyOpenTelemetry implements Telemetry {
                 )
               : undefined,
         },
-        'ai.response.providerMetadata': event.providerMetadata
-          ? JSON.stringify(event.providerMetadata)
+        'ai.response.providerMetadata': event.finalStep.providerMetadata
+          ? JSON.stringify(event.finalStep.providerMetadata)
           : undefined,
 
-        'ai.usage.inputTokens': event.totalUsage.inputTokens,
-        'ai.usage.outputTokens': event.totalUsage.outputTokens,
-        'ai.usage.totalTokens': event.totalUsage.totalTokens,
+        'ai.usage.inputTokens': event.usage.inputTokens,
+        'ai.usage.outputTokens': event.usage.outputTokens,
+        'ai.usage.totalTokens': event.usage.totalTokens,
         'ai.usage.reasoningTokens':
-          event.totalUsage.outputTokenDetails?.reasoningTokens,
+          event.usage.outputTokenDetails?.reasoningTokens,
         'ai.usage.cachedInputTokens':
-          event.totalUsage.inputTokenDetails?.cacheReadTokens,
+          event.usage.inputTokenDetails?.cacheReadTokens,
         'ai.usage.inputTokenDetails.noCacheTokens':
-          event.totalUsage.inputTokenDetails?.noCacheTokens,
+          event.usage.inputTokenDetails?.noCacheTokens,
         'ai.usage.inputTokenDetails.cacheReadTokens':
-          event.totalUsage.inputTokenDetails?.cacheReadTokens,
+          event.usage.inputTokenDetails?.cacheReadTokens,
         'ai.usage.inputTokenDetails.cacheWriteTokens':
-          event.totalUsage.inputTokenDetails?.cacheWriteTokens,
+          event.usage.inputTokenDetails?.cacheWriteTokens,
         'ai.usage.outputTokenDetails.textTokens':
-          event.totalUsage.outputTokenDetails?.textTokens,
+          event.usage.outputTokenDetails?.textTokens,
         'ai.usage.outputTokenDetails.reasoningTokens':
-          event.totalUsage.outputTokenDetails?.reasoningTokens,
+          event.usage.outputTokenDetails?.reasoningTokens,
       }),
     );
 
@@ -1067,6 +1100,35 @@ export class LegacyOpenTelemetry implements Telemetry {
     state.rerankSpan = undefined;
   }
 
+  onAbort(event: GenerateTextAbortEvent<ToolSet>): void {
+    const state = this.getCallState(event.callId);
+    if (!state?.rootSpan) return;
+
+    for (const { span: toolSpan } of state.toolSpans.values()) {
+      toolSpan.end();
+    }
+    state.toolSpans.clear();
+
+    if (state.stepSpan) {
+      state.stepSpan.end();
+      state.stepSpan = undefined;
+      state.stepContext = undefined;
+    }
+
+    for (const { span: embedSpan } of state.embedSpans.values()) {
+      embedSpan.end();
+    }
+    state.embedSpans.clear();
+
+    if (state.rerankSpan) {
+      state.rerankSpan.span.end();
+      state.rerankSpan = undefined;
+    }
+
+    state.rootSpan.end();
+    this.cleanupCallState(event.callId);
+  }
+
   onError(error: unknown): void {
     const event = error as { callId?: string; error?: unknown };
     if (!event?.callId) return;

package/src/open-telemetry.ts

@@ -18,6 +18,7 @@ import type {
   GenerateObjectStartEvent,
   GenerateObjectStepEndEvent,
   GenerateObjectStepStartEvent,
+  GenerateTextAbortEvent,
   GenerateTextEndEvent,
   GenerateTextStartEvent,
   GenerateTextStepEndEvent,
@@ -43,6 +44,7 @@ import {
   mapProviderName,
 } from './gen-ai-format-messages';
 import { recordErrorOnSpan } from './record-span';
+import { sanitizeAttributes } from './sanitize-attribute-value';
 import { selectAttributes } from './select-attributes';
 import {
   getDetailedUsageAttributes,
@@ -85,6 +87,24 @@ interface CallState {
   baseSupplementalAttributes: Attributes;
 }
 
+function msToSeconds(durationMs: number | undefined): number | undefined {
+  return durationMs == null ? undefined : durationMs / 1000;
+}
+
+function getGenAIClientPerformanceAttributes(
+  performance: LanguageModelCallEndEvent<ToolSet>['performance'],
+): Attributes {
+  return {
+    'gen_ai.client.operation.duration': msToSeconds(performance.responseTimeMs),
+    'gen_ai.client.operation.time_to_first_chunk': msToSeconds(
+      performance.timeToFirstOutputMs,
+    ),
+    'gen_ai.client.operation.time_per_output_chunk': msToSeconds(
+      performance.timeBetweenOutputChunksMs?.avg,
+    ),
+  };
+}
+
 export class OpenTelemetry implements Telemetry {
   private readonly callStates = new Map<string, CallState>();
 
@@ -133,7 +153,7 @@ export class OpenTelemetry implements Telemetry {
     }
 
     return {
-      ...customAttributes,
+      ...sanitizeAttributes(customAttributes),
       ...attributes,
     };
   }
@@ -156,6 +176,27 @@ export class OpenTelemetry implements Telemetry {
     return context.with(toolSpanEntry.context, execute);
   }
 
+  /**
+   * Runs the provider `doGenerate`/`doStream` call with the active model-call
+   * context.
+   */
+  executeLanguageModelCall<T>({
+    callId,
+    execute,
+  }: {
+    callId: string;
+    execute: () => PromiseLike<T>;
+  }): PromiseLike<T> {
+    const state = this.getCallState(callId);
+    const modelCallContext = state?.inferenceContext ?? state?.stepContext;
+
+    if (modelCallContext == null) {
+      return execute();
+    }
+
+    return context.with(modelCallContext, execute);
+  }
+
   onStart(
     event:
       | InferTelemetryEvent<GenerateTextStartEvent>
@@ -456,7 +497,7 @@ export class OpenTelemetry implements Telemetry {
   }
 
   /** @deprecated */
-  onObjectStepFinish(event: GenerateObjectStepEndEvent): void {
+  onObjectStepEnd(event: GenerateObjectStepEndEvent): void {
     const state = this.getCallState(event.callId);
     if (!state?.inferenceSpan) return;
 
@@ -691,6 +732,7 @@ export class OpenTelemetry implements Telemetry {
 
     state.inferenceSpan.setAttributes(
       selectAttributes(telemetry, {
+        ...getGenAIClientPerformanceAttributes(event.performance),
         'gen_ai.response.finish_reasons': [event.finishReason],
         'gen_ai.response.id': event.responseId,
         'gen_ai.usage.input_tokens': event.usage.inputTokens,
@@ -783,6 +825,12 @@ export class OpenTelemetry implements Telemetry {
     const { telemetry } = state;
 
     const { toolOutput } = event;
+    span.setAttributes(
+      selectAttributes(telemetry, {
+        'gen_ai.execute_tool.duration': msToSeconds(event.toolExecutionMs),
+      }),
+    );
+
     if (toolOutput.type === 'tool-result') {
       try {
         span.setAttributes(
@@ -803,7 +851,7 @@ export class OpenTelemetry implements Telemetry {
     state.toolSpans.delete(event.toolCall.toolCallId);
   }
 
-  onStepFinish(event: GenerateTextStepEndEvent<ToolSet>): void {
+  onStepEnd(event: GenerateTextStepEndEvent<ToolSet>): void {
     const state = this.getCallState(event.callId);
     if (!state?.stepSpan) return;
 
@@ -825,6 +873,11 @@ export class OpenTelemetry implements Telemetry {
     state.stepContext = undefined;
   }
 
+  /** @deprecated Use `onStepEnd` instead. */
+  onStepFinish(event: GenerateTextStepEndEvent<ToolSet>): void {
+    this.onStepEnd(event);
+  }
+
   onEnd(
     event:
       | GenerateTextEndEvent<ToolSet>
@@ -868,18 +921,20 @@ export class OpenTelemetry implements Telemetry {
     state.rootSpan.setAttributes(
       selectAttributes(telemetry, {
         'gen_ai.response.finish_reasons': [event.finishReason],
-        'gen_ai.usage.input_tokens': event.totalUsage.inputTokens,
-        'gen_ai.usage.output_tokens': event.totalUsage.outputTokens,
+        'gen_ai.usage.input_tokens': event.usage.inputTokens,
+        'gen_ai.usage.output_tokens': event.usage.outputTokens,
         'gen_ai.usage.cache_read.input_tokens':
-          event.totalUsage.inputTokenDetails?.cacheReadTokens,
+          event.usage.inputTokenDetails?.cacheReadTokens,
         'gen_ai.usage.cache_creation.input_tokens':
-          event.totalUsage.inputTokenDetails?.cacheWriteTokens,
+          event.usage.inputTokenDetails?.cacheWriteTokens,
         'gen_ai.output.messages': {
           output: () =>
             JSON.stringify(
               formatOutputMessages({
                 text: event.text ?? undefined,
-                reasoning: event.reasoning as ReadonlyArray<{ text?: string }>,
+                reasoning: event.finalStep.reasoning as ReadonlyArray<{
+                  text?: string;
+                }>,
                 toolCalls: event.toolCalls,
                 files: event.files,
                 finishReason: event.finishReason,
@@ -891,11 +946,11 @@ export class OpenTelemetry implements Telemetry {
           this.supplementalAttributes,
           {
             providerMetadata: {
-              'ai.response.providerMetadata': event.providerMetadata
-                ? JSON.stringify(event.providerMetadata)
+              'ai.response.providerMetadata': event.finalStep.providerMetadata
+                ? JSON.stringify(event.finalStep.providerMetadata)
                 : undefined,
             },
-            usage: getDetailedUsageAttributes(event.totalUsage),
+            usage: getDetailedUsageAttributes(event.usage),
           },
         ),
       }),
@@ -1197,6 +1252,41 @@ export class OpenTelemetry implements Telemetry {
     state.rerankSpan = undefined;
   }
 
+  onAbort(event: GenerateTextAbortEvent<ToolSet>): void {
+    const state = this.getCallState(event.callId);
+    if (!state?.rootSpan) return;
+
+    for (const { span: toolSpan } of state.toolSpans.values()) {
+      toolSpan.end();
+    }
+    state.toolSpans.clear();
+
+    if (state.inferenceSpan) {
+      state.inferenceSpan.end();
+      state.inferenceSpan = undefined;
+      state.inferenceContext = undefined;
+    }
+
+    if (state.stepSpan) {
+      state.stepSpan.end();
+      state.stepSpan = undefined;
+      state.stepContext = undefined;
+    }
+
+    for (const { span: embedSpan } of state.embedSpans.values()) {
+      embedSpan.end();
+    }
+    state.embedSpans.clear();
+
+    if (state.rerankSpan) {
+      state.rerankSpan.span.end();
+      state.rerankSpan = undefined;
+    }
+
+    state.rootSpan.end();
+    this.cleanupCallState(event.callId);
+  }
+
   onError(error: unknown): void {
     const event = error as { callId?: string; error?: unknown };
     if (!event?.callId) return;

package/src/sanitize-attribute-value.ts

@@ -0,0 +1,53 @@
+import type { Attributes, AttributeValue } from '@opentelemetry/api';
+
+function isPrimitiveAttributeValue(
+  value: unknown,
+): value is string | number | boolean {
+  return (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  );
+}
+
+export function sanitizeAttributeValue(
+  value: AttributeValue,
+): AttributeValue | undefined {
+  if (!Array.isArray(value)) {
+    return value;
+  }
+
+  const primitiveTypes = new Set(
+    value.filter(isPrimitiveAttributeValue).map(item => typeof item),
+  );
+
+  if (primitiveTypes.size !== 1) {
+    return undefined;
+  }
+
+  const [primitiveType] = primitiveTypes;
+
+  if (primitiveType === 'string') {
+    return value.filter((item): item is string => typeof item === 'string');
+  }
+
+  if (primitiveType === 'number') {
+    return value.filter((item): item is number => typeof item === 'number');
+  }
+
+  return value.filter((item): item is boolean => typeof item === 'boolean');
+}
+
+export function sanitizeAttributes(
+  attributes: Attributes | undefined,
+): Attributes {
+  const result: Attributes = {};
+
+  for (const [key, value] of Object.entries(attributes ?? {})) {
+    if (value == null) continue;
+    const sanitized = sanitizeAttributeValue(value);
+    if (sanitized != null) result[key] = sanitized;
+  }
+
+  return result;
+}

package/src/select-attributes.ts

@@ -1,5 +1,6 @@
 import type { Attributes, AttributeValue } from '@opentelemetry/api';
 import type { TelemetryOptions } from 'ai';
+import { sanitizeAttributeValue } from './sanitize-attribute-value';
 
 export type AttributeSpec =
   | AttributeValue
@@ -35,7 +36,10 @@ export function selectAttributes(
     ) {
       if (telemetry?.recordInputs === false) continue;
       const resolved = value.input();
-      if (resolved != null) result[key] = resolved;
+      if (resolved != null) {
+        const sanitized = sanitizeAttributeValue(resolved);
+        if (sanitized != null) result[key] = sanitized;
+      }
       continue;
     }
 
@@ -46,11 +50,15 @@ export function selectAttributes(
     ) {
       if (telemetry?.recordOutputs === false) continue;
       const resolved = value.output();
-      if (resolved != null) result[key] = resolved;
+      if (resolved != null) {
+        const sanitized = sanitizeAttributeValue(resolved);
+        if (sanitized != null) result[key] = sanitized;
+      }
       continue;
     }
 
-    result[key] = value as AttributeValue;
+    const sanitized = sanitizeAttributeValue(value as AttributeValue);
+    if (sanitized != null) result[key] = sanitized;
   }
 
   return result;

package/src/supplemental-attributes.ts

@@ -1,6 +1,10 @@
 import type { Attributes, Tracer } from '@opentelemetry/api';
 import type { TelemetryOptions } from 'ai';
-import { selectAttributes, type AttributeSpecMap } from './select-attributes';
+import {
+  selectAttributes,
+  type AttributeSpec,
+  type AttributeSpecMap,
+} from './select-attributes';
 
 type SupplementalAttributeOption =
   | 'usage'
@@ -115,11 +119,36 @@ export function normalizeSupplementalAttributes(
 export function getRuntimeContextAttributes(
   context: Record<string, unknown> | undefined,
 ): AttributeSpecMap {
-  return Object.fromEntries(
-    Object.entries(context ?? {})
-      .filter(([, value]) => value != null)
-      .map(([key, value]) => [`ai.settings.context.${key}`, value]),
-  ) as AttributeSpecMap;
+  const attributes: AttributeSpecMap = {};
+
+  for (const [key, value] of Object.entries(context ?? {})) {
+    addRuntimeContextAttribute(attributes, `ai.settings.context.${key}`, value);
+  }
+
+  return attributes;
+}
+
+/**
+ * Flattens nested runtime context objects into OTel-compatible attribute keys.
+ * Arrays are preserved because OTel supports primitive array attribute values.
+ */
+function addRuntimeContextAttribute(
+  attributes: AttributeSpecMap,
+  key: string,
+  value: unknown,
+): void {
+  if (value == null) {
+    return;
+  }
+
+  if (Array.isArray(value) || typeof value !== 'object') {
+    attributes[key] = value as AttributeSpec;
+    return;
+  }
+
+  for (const [nestedKey, nestedValue] of Object.entries(value)) {
+    addRuntimeContextAttribute(attributes, `${key}.${nestedKey}`, nestedValue);
+  }
 }
 
 export function getHeaderAttributes(