@ai-sdk/otel 0.0.0-6b196531-20260710185421

package/src/record-span.ts

@@ -0,0 +1,74 @@
+import {
+  SpanStatusCode,
+  context,
+  type Attributes,
+  type Span,
+  type Tracer,
+} from '@opentelemetry/api';
+export async function recordSpan<T>({
+  name,
+  tracer,
+  attributes,
+  fn,
+  endWhenDone = true,
+}: {
+  name: string;
+  tracer: Tracer;
+  attributes: Attributes | PromiseLike<Attributes>;
+  fn: (span: Span) => Promise<T>;
+  endWhenDone?: boolean;
+}) {
+  return tracer.startActiveSpan(
+    name,
+    { attributes: await attributes },
+    async span => {
+      // Capture the current context to maintain it across async generator yields
+      const ctx = context.active();
+
+      try {
+        // Execute within the captured context to ensure async generators
+        // don't lose the active span when they yield
+        const result = await context.with(ctx, () => fn(span));
+
+        if (endWhenDone) {
+          span.end();
+        }
+
+        return result;
+      } catch (error) {
+        try {
+          recordErrorOnSpan(span, error);
+        } finally {
+          // always stop the span when there is an error:
+          span.end();
+        }
+
+        throw error;
+      }
+    },
+  );
+}
+
+/**
+ * Record an error on a span. Sets the span status to error. If the error is
+ * an instance of Error, an exception event with name, message, and stack
+ * will also be recorded.
+ *
+ * @param span - The span to record the error on.
+ * @param error - The error to record on the span.
+ */
+export function recordErrorOnSpan(span: Span, error: unknown) {
+  if (error instanceof Error) {
+    span.recordException({
+      name: error.name,
+      message: error.message,
+      stack: error.stack,
+    });
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error.message,
+    });
+  } else {
+    span.setStatus({ code: SpanStatusCode.ERROR });
+  }
+}

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

@@ -0,0 +1,65 @@
+import type { Attributes, AttributeValue } from '@opentelemetry/api';
+import type { TelemetryOptions } from 'ai';
+import { sanitizeAttributeValue } from './sanitize-attribute-value';
+
+export type AttributeSpec =
+  | AttributeValue
+  | { input: () => AttributeValue | undefined }
+  | { output: () => AttributeValue | undefined }
+  | undefined;
+
+export type AttributeSpecMap = Record<string, AttributeSpec>;
+
+function shouldRecord(
+  telemetry: TelemetryOptions | undefined,
+): telemetry is TelemetryOptions {
+  return telemetry?.isEnabled !== false;
+}
+
+export function selectAttributes(
+  telemetry: TelemetryOptions | undefined,
+  attributes: AttributeSpecMap,
+): Attributes {
+  if (!shouldRecord(telemetry)) {
+    return {};
+  }
+
+  const result: Attributes = {};
+
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value == null) continue;
+
+    if (
+      typeof value === 'object' &&
+      'input' in value &&
+      typeof value.input === 'function'
+    ) {
+      if (telemetry?.recordInputs === false) continue;
+      const resolved = value.input();
+      if (resolved != null) {
+        const sanitized = sanitizeAttributeValue(resolved);
+        if (sanitized != null) result[key] = sanitized;
+      }
+      continue;
+    }
+
+    if (
+      typeof value === 'object' &&
+      'output' in value &&
+      typeof value.output === 'function'
+    ) {
+      if (telemetry?.recordOutputs === false) continue;
+      const resolved = value.output();
+      if (resolved != null) {
+        const sanitized = sanitizeAttributeValue(resolved);
+        if (sanitized != null) result[key] = sanitized;
+      }
+      continue;
+    }
+
+    const sanitized = sanitizeAttributeValue(value as AttributeValue);
+    if (sanitized != null) result[key] = sanitized;
+  }
+
+  return result;
+}

package/src/select-telemetry-attributes.ts

@@ -0,0 +1,78 @@
+import type { Attributes, AttributeValue } from '@opentelemetry/api';
+import type { TelemetryOptions } from 'ai';
+
+type ResolvableAttributeValue = () =>
+  | AttributeValue
+  | PromiseLike<AttributeValue>
+  | undefined;
+
+export async function selectTelemetryAttributes({
+  telemetry,
+  attributes,
+}: {
+  telemetry?: TelemetryOptions;
+  attributes: {
+    [attributeKey: string]:
+      | AttributeValue
+      | { input: ResolvableAttributeValue }
+      | { output: ResolvableAttributeValue }
+      | undefined;
+  };
+}): Promise<Attributes> {
+  // when telemetry is disabled, return an empty object to avoid serialization overhead:
+  if (telemetry?.isEnabled === false) {
+    return {};
+  }
+
+  const resultAttributes: Attributes = {};
+
+  for (const [key, value] of Object.entries(attributes)) {
+    if (value == null) {
+      continue;
+    }
+
+    // input value, check if it should be recorded:
+    if (
+      typeof value === 'object' &&
+      'input' in value &&
+      typeof value.input === 'function'
+    ) {
+      // default to true:
+      if (telemetry?.recordInputs === false) {
+        continue;
+      }
+
+      const result = await value.input();
+
+      if (result != null) {
+        resultAttributes[key] = result;
+      }
+
+      continue;
+    }
+
+    // output value, check if it should be recorded:
+    if (
+      typeof value === 'object' &&
+      'output' in value &&
+      typeof value.output === 'function'
+    ) {
+      // default to true:
+      if (telemetry?.recordOutputs === false) {
+        continue;
+      }
+
+      const result = await value.output();
+
+      if (result != null) {
+        resultAttributes[key] = result;
+      }
+      continue;
+    }
+
+    // value is an attribute value already:
+    resultAttributes[key] = value as AttributeValue;
+  }
+
+  return resultAttributes;
+}

package/src/stringify-for-telemetry.ts

@@ -0,0 +1,51 @@
+import type {
+  LanguageModelV4Message,
+  LanguageModelV4Prompt,
+} from '@ai-sdk/provider';
+import { convertDataContentToBase64String } from 'ai';
+
+/**
+ * Helper utility to serialize prompt content for OpenTelemetry tracing.
+ * It is initially created because normalized LanguageModelV4Prompt carries
+ * images as Uint8Arrays, on which JSON.stringify acts weirdly, converting
+ * them to objects with stringified indices as keys, e.g. {"0": 42, "1": 69 }.
+ */
+export function stringifyForTelemetry(prompt: LanguageModelV4Prompt): string {
+  return JSON.stringify(
+    prompt.map((message: LanguageModelV4Message) => ({
+      ...message,
+      content:
+        typeof message.content === 'string'
+          ? message.content
+          : message.content.map(part =>
+              part.type === 'file'
+                ? {
+                    ...part,
+                    data: serializeFileData(part.data),
+                  }
+                : part,
+            ),
+    })),
+  );
+}
+
+function serializeFileData(
+  data:
+    | { type: 'data'; data: string | Uint8Array }
+    | { type: 'url'; url: URL }
+    | { type: 'reference'; reference: Record<string, string> }
+    | { type: 'text'; text: string },
+): unknown {
+  switch (data.type) {
+    case 'data':
+      return data.data instanceof Uint8Array
+        ? convertDataContentToBase64String(data.data)
+        : data.data;
+    case 'url':
+      return data.url.toString();
+    case 'reference':
+      return data.reference;
+    case 'text':
+      return data.text;
+  }
+}

package/src/supplemental-attributes.ts

@@ -0,0 +1,201 @@
+import type { Attributes, Tracer } from '@opentelemetry/api';
+import type { TelemetryOptions } from 'ai';
+import {
+  selectAttributes,
+  type AttributeSpec,
+  type AttributeSpecMap,
+} from './select-attributes';
+
+type SupplementalAttributeOption =
+  | 'usage'
+  | 'providerMetadata'
+  | 'embedding'
+  | 'reranking'
+  | 'runtimeContext'
+  | 'headers'
+  | 'toolChoice'
+  | 'schema';
+
+export type SupplementalAttributeOptions = Record<
+  SupplementalAttributeOption,
+  boolean
+>;
+
+export type OpenTelemetrySpanType =
+  | 'operation'
+  | 'step'
+  | 'languageModel'
+  | 'tool'
+  | 'embedding'
+  | 'reranking';
+
+export type EnrichSpan = (options: {
+  spanType: OpenTelemetrySpanType;
+  operationId: string;
+  callId: string;
+  runtimeContext: Record<string, unknown> | undefined;
+}) => Attributes | undefined;
+
+export type OpenTelemetryOptions = {
+  /**
+   * The tracer to use for the telemetry data.
+   */
+  tracer?: Tracer;
+
+  /**
+   * Adds custom attributes to spans when they are created. These attributes are
+   * not AI SDK-owned semantics and are intended for observability integrations.
+   */
+  enrichSpan?: EnrichSpan;
+
+  /**
+   * Emit AI SDK usage details that are not represented by GenAI SemConv.
+   */
+  usage?: boolean;
+
+  /**
+   * Emit provider metadata on response spans.
+   */
+  providerMetadata?: boolean;
+
+  /**
+   * Emit embedding input and output values.
+   */
+  embedding?: boolean;
+
+  /**
+   * Emit reranking input documents and output ranking.
+   */
+  reranking?: boolean;
+
+  /**
+   * Emit runtime context values.
+   */
+  runtimeContext?: boolean;
+
+  /**
+   * Emit request headers.
+   */
+  headers?: boolean;
+
+  /**
+   * Emit selected tool choice information.
+   */
+  toolChoice?: boolean;
+
+  /**
+   * Emit object generation schema information.
+   */
+  schema?: boolean;
+};
+
+const disabledSupplementalAttributes: SupplementalAttributeOptions = {
+  usage: false,
+  providerMetadata: false,
+  embedding: false,
+  reranking: false,
+  runtimeContext: false,
+  headers: false,
+  toolChoice: false,
+  schema: false,
+};
+
+export function normalizeSupplementalAttributes(
+  options: OpenTelemetryOptions,
+): SupplementalAttributeOptions {
+  return {
+    ...disabledSupplementalAttributes,
+    usage: options.usage ?? false,
+    providerMetadata: options.providerMetadata ?? false,
+    embedding: options.embedding ?? false,
+    reranking: options.reranking ?? false,
+    runtimeContext: options.runtimeContext ?? false,
+    headers: options.headers ?? false,
+    toolChoice: options.toolChoice ?? false,
+    schema: options.schema ?? false,
+  };
+}
+
+export function getRuntimeContextAttributes(
+  context: Record<string, unknown> | undefined,
+): 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(
+  headers: Record<string, string | undefined> | undefined,
+): AttributeSpecMap {
+  return Object.fromEntries(
+    Object.entries(headers ?? {})
+      .filter(([, value]) => value != null)
+      .map(([key, value]) => [`ai.request.headers.${key}`, value]),
+  ) as AttributeSpecMap;
+}
+
+export function getDetailedUsageAttributes(usage: {
+  inputTokenDetails?: {
+    noCacheTokens?: number | undefined;
+  };
+  outputTokenDetails?: {
+    textTokens?: number | undefined;
+    reasoningTokens?: number | undefined;
+  };
+}): AttributeSpecMap {
+  return {
+    'ai.usage.inputTokenDetails.noCacheTokens':
+      usage.inputTokenDetails?.noCacheTokens,
+    'ai.usage.outputTokenDetails.textTokens':
+      usage.outputTokenDetails?.textTokens,
+    'ai.usage.outputTokenDetails.reasoningTokens':
+      usage.outputTokenDetails?.reasoningTokens,
+  };
+}
+
+export function selectSupplementalAttributes(
+  telemetry: TelemetryOptions | undefined,
+  enabledAttributes: SupplementalAttributeOptions,
+  attributes: Partial<Record<SupplementalAttributeOption, AttributeSpecMap>>,
+): Attributes {
+  const result: Attributes = {};
+
+  for (const [key, value] of Object.entries(attributes) as Array<
+    [SupplementalAttributeOption, AttributeSpecMap | undefined]
+  >) {
+    if (!enabledAttributes[key] || value == null) {
+      continue;
+    }
+
+    Object.assign(result, selectAttributes(telemetry, value));
+  }
+
+  return result;
+}