@ai-sdk/otel 1.0.0-beta.13 → 1.0.0-beta.130

package/README.md

@@ -0,0 +1,119 @@
+# AI SDK - OpenTelemetry
+
+The **OpenTelemetry integration** for the [AI SDK](https://ai-sdk.dev/docs)
+collects tracing spans for AI SDK calls and sends them through your configured
+OpenTelemetry setup.
+
+## Setup
+
+The OpenTelemetry integration is available in the `@ai-sdk/otel` module. You can
+install it with
+
+```bash
+npm i @ai-sdk/otel
+```
+
+## Skill for Coding Agents
+
+If you use coding agents such as Claude Code or Cursor, we highly recommend
+adding the AI SDK skill to your repository:
+
+```shell
+npx skills add vercel/ai
+```
+
+## Usage
+
+Register the telemetry integration once at application startup with
+`registerTelemetry()`:
+
+```ts
+import { OpenTelemetry } from '@ai-sdk/otel';
+import { registerTelemetry } from 'ai';
+
+registerTelemetry(new OpenTelemetry());
+```
+
+For Next.js applications, place this in `instrumentation.ts` alongside your
+OpenTelemetry provider setup. For Node.js applications, register it at the top
+level of your entry file.
+
+Once registered, AI SDK calls emit telemetry events by default:
+
+```ts
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: 'openai/gpt-5.4',
+  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+  telemetry: {
+    functionId: 'recipe-generator',
+  },
+});
+```
+
+You can opt out for an individual call with `telemetry.isEnabled`:
+
+```ts
+const result = await generateText({
+  model: 'openai/gpt-5.4',
+  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+  telemetry: {
+    isEnabled: false,
+  },
+});
+```
+
+## OpenTelemetry
+
+`OpenTelemetry` is the recommended integration. It emits spans that follow the
+[OpenTelemetry GenAI Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/).
+
+You can pass a custom tracer when you want to use a specific `TracerProvider`:
+
+```ts
+import { OpenTelemetry } from '@ai-sdk/otel';
+import { registerTelemetry } from 'ai';
+
+registerTelemetry(
+  new OpenTelemetry({
+    tracer: tracerProvider.getTracer('gen_ai'),
+  }),
+);
+```
+
+You can also add custom attributes to spans with `enrichSpan`:
+
+```ts
+import { OpenTelemetry } from '@ai-sdk/otel';
+import { registerTelemetry } from 'ai';
+
+registerTelemetry(
+  new OpenTelemetry({
+    enrichSpan: ({ spanType, operationId, callId }) => ({
+      'my_app.span_type': spanType,
+      'my_app.operation_id': operationId,
+      'my_app.call_id': callId,
+    }),
+  }),
+);
+```
+
+## Legacy Telemetry
+
+`LegacyOpenTelemetry` emits the older AI SDK-specific span format with `ai.*`
+attributes. Use it when an existing observability integration depends on the
+legacy span shape:
+
+```ts
+import { LegacyOpenTelemetry } from '@ai-sdk/otel';
+import { registerTelemetry } from 'ai';
+
+registerTelemetry(new LegacyOpenTelemetry());
+```
+
+## Documentation
+
+Please check out the
+[AI SDK telemetry documentation](https://ai-sdk.dev/docs/ai-sdk-core/telemetry)
+for more information.

package/dist/index.d.ts

@@ -1,13 +1,120 @@
+import { Telemetry, InferTelemetryEvent, GenerateTextStartEvent, GenerateObjectStartEvent, EmbedStartEvent, RerankStartEvent, GenerateObjectStepStartEvent, GenerateObjectStepEndEvent, GenerateTextStepStartEvent, ToolSet, LanguageModelCallStartEvent, LanguageModelCallEndEvent, ToolExecutionStartEvent, ToolExecutionEndEvent, GenerateTextStepEndEvent, GenerateTextEndEvent, GenerateObjectEndEvent, EmbedEndEvent, RerankEndEvent, EmbeddingModelCallStartEvent, EmbeddingModelCallEndEvent, RerankingModelCallStartEvent, RerankingModelCallEndEvent, GenerateTextAbortEvent, Output } from 'ai';
+import { Attributes, Tracer } from '@opentelemetry/api';
 import { LanguageModelV4Prompt } from '@ai-sdk/provider';
-import { Tracer } from '@opentelemetry/api';
-import { TelemetryIntegration, OnStartEvent, ToolSet, OutputInterface, ObjectOnStartEvent, EmbedOnStartEvent, RerankOnStartEvent, ObjectOnStepStartEvent, ObjectOnStepFinishEvent, GenerationContext, OnStepStartEvent, OnToolCallStartEvent, OnToolCallFinishEvent, OnStepFinishEvent, OnFinishEvent, ObjectOnFinishEvent, EmbedOnFinishEvent, RerankOnFinishEvent, EmbedStartEvent, EmbedFinishEvent, RerankStartEvent, RerankFinishEvent, OnChunkEvent } from 'ai';
+import { Context } from '@ai-sdk/provider-utils';
 
-interface OtelStepStartEvent<TOOLS extends ToolSet = ToolSet, CONTEXT extends GenerationContext<TOOLS> = GenerationContext<TOOLS>, OUTPUT extends OutputInterface = OutputInterface> extends OnStepStartEvent<TOOLS, CONTEXT, OUTPUT> {
+type OpenTelemetrySpanType = 'operation' | 'step' | 'languageModel' | 'tool' | 'embedding' | 'reranking';
+type EnrichSpan = (options: {
+    spanType: OpenTelemetrySpanType;
+    operationId: string;
+    callId: string;
+    runtimeContext: Record<string, unknown> | undefined;
+}) => Attributes | undefined;
+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;
+};
+
+interface OtelStepStartEvent$1 extends GenerateTextStepStartEvent<ToolSet> {
+    readonly stepToolChoice?: unknown;
+}
+declare class OpenTelemetry implements Telemetry {
+    private readonly callStates;
+    private readonly tracer;
+    private readonly supplementalAttributes;
+    private readonly enrichSpan;
+    constructor(options?: OpenTelemetryOptions);
+    private getCallState;
+    private cleanupCallState;
+    private getSpanAttributes;
+    executeTool<T>({ callId, toolCallId, execute, }: {
+        callId: string;
+        toolCallId: string;
+        execute: () => PromiseLike<T>;
+    }): PromiseLike<T>;
+    /**
+     * Runs the provider `doGenerate`/`doStream` call with the active model-call
+     * context.
+     */
+    executeLanguageModelCall<T>({ callId, execute, }: {
+        callId: string;
+        execute: () => PromiseLike<T>;
+    }): PromiseLike<T>;
+    onStart(event: InferTelemetryEvent<GenerateTextStartEvent> | InferTelemetryEvent<GenerateObjectStartEvent> | InferTelemetryEvent<EmbedStartEvent> | InferTelemetryEvent<RerankStartEvent>): void;
+    private onGenerateStart;
+    private onObjectOperationStart;
+    /** @deprecated */
+    onObjectStepStart(event: GenerateObjectStepStartEvent): void;
+    /** @deprecated */
+    onObjectStepEnd(event: GenerateObjectStepEndEvent): void;
+    private onEmbedOperationStart;
+    onStepStart(event: OtelStepStartEvent$1): void;
+    onLanguageModelCallStart(event: LanguageModelCallStartEvent): void;
+    onLanguageModelCallEnd(event: LanguageModelCallEndEvent<ToolSet>): void;
+    onToolExecutionStart(event: ToolExecutionStartEvent<ToolSet>): void;
+    onToolExecutionEnd(event: ToolExecutionEndEvent<ToolSet>): void;
+    onStepEnd(event: GenerateTextStepEndEvent<ToolSet>): void;
+    /** @deprecated Use `onStepEnd` instead. */
+    onStepFinish(event: GenerateTextStepEndEvent<ToolSet>): void;
+    onEnd(event: GenerateTextEndEvent<ToolSet> | GenerateObjectEndEvent<unknown> | EmbedEndEvent | RerankEndEvent): void;
+    private onGenerateEnd;
+    private onObjectOperationEnd;
+    private onEmbedOperationEnd;
+    onEmbedStart(event: EmbeddingModelCallStartEvent): void;
+    onEmbedEnd(event: EmbeddingModelCallEndEvent): void;
+    private onRerankOperationStart;
+    private onRerankOperationEnd;
+    onRerankStart(event: RerankingModelCallStartEvent): void;
+    onRerankEnd(event: RerankingModelCallEndEvent): void;
+    onAbort(event: GenerateTextAbortEvent<ToolSet>): void;
+    onError(error: unknown): void;
+}
+
+interface OtelStepStartEvent<TOOLS extends ToolSet = ToolSet, RUNTIME_CONTEXT extends Context = Context, OUTPUT extends Output.Output = Output.Output> extends GenerateTextStepStartEvent<TOOLS, RUNTIME_CONTEXT, OUTPUT> {
     readonly promptMessages?: LanguageModelV4Prompt;
     readonly stepTools?: ReadonlyArray<Record<string, unknown>>;
     readonly stepToolChoice?: unknown;
 }
-declare class OpenTelemetryIntegration implements TelemetryIntegration {
+declare class LegacyOpenTelemetry implements Telemetry {
     private readonly callStates;
     /**
      * The tracer to use for the telemetry data.
@@ -23,30 +130,40 @@ declare class OpenTelemetryIntegration implements TelemetryIntegration {
         toolCallId: string;
         execute: () => PromiseLike<T>;
     }): PromiseLike<T>;
-    onStart(event: OnStartEvent<ToolSet, OutputInterface> | ObjectOnStartEvent | EmbedOnStartEvent | RerankOnStartEvent): void;
+    /**
+     * Runs the provider `doGenerate`/`doStream` call with the active legacy
+     * model-call context.
+     */
+    executeLanguageModelCall<T>({ callId, execute, }: {
+        callId: string;
+        execute: () => PromiseLike<T>;
+    }): PromiseLike<T>;
+    onStart(event: InferTelemetryEvent<GenerateTextStartEvent> | InferTelemetryEvent<GenerateObjectStartEvent> | InferTelemetryEvent<EmbedStartEvent> | InferTelemetryEvent<RerankStartEvent>): void;
     private onGenerateStart;
     private onObjectOperationStart;
     /** @deprecated */
-    onObjectStepStart(event: ObjectOnStepStartEvent): void;
+    onObjectStepStart(event: GenerateObjectStepStartEvent): void;
     /** @deprecated */
-    onObjectStepFinish(event: ObjectOnStepFinishEvent): void;
+    onObjectStepEnd(event: GenerateObjectStepEndEvent): void;
     private onEmbedOperationStart;
-    onStepStart(event: OtelStepStartEvent<ToolSet, OutputInterface>): void;
-    onToolCallStart(event: OnToolCallStartEvent<ToolSet>): void;
-    onToolCallFinish(event: OnToolCallFinishEvent<ToolSet>): void;
-    onStepFinish(event: OnStepFinishEvent<ToolSet>): void;
-    onFinish(event: OnFinishEvent<ToolSet> | ObjectOnFinishEvent<unknown> | EmbedOnFinishEvent | RerankOnFinishEvent): void;
-    private onGenerateFinish;
-    private onObjectOperationFinish;
-    private onEmbedOperationFinish;
-    onEmbedStart(event: EmbedStartEvent): void;
-    onEmbedFinish(event: EmbedFinishEvent): void;
+    onStepStart(event: OtelStepStartEvent): void;
+    onToolExecutionStart(event: ToolExecutionStartEvent<ToolSet>): void;
+    onToolExecutionEnd(event: ToolExecutionEndEvent<ToolSet>): void;
+    onStepEnd(event: GenerateTextStepEndEvent<ToolSet>): void;
+    /** @deprecated Use `onStepEnd` instead. */
+    onStepFinish(event: GenerateTextStepEndEvent<ToolSet>): void;
+    onEnd(event: GenerateTextEndEvent<ToolSet> | GenerateObjectEndEvent<unknown> | EmbedEndEvent | RerankEndEvent): void;
+    private onGenerateEnd;
+    private onObjectOperationEnd;
+    private onEmbedOperationEnd;
+    onEmbedStart(event: EmbeddingModelCallStartEvent): void;
+    onEmbedEnd(event: EmbeddingModelCallEndEvent): void;
     private onRerankOperationStart;
-    private onRerankOperationFinish;
-    onRerankStart(event: RerankStartEvent): void;
-    onRerankFinish(event: RerankFinishEvent): void;
-    onChunk(event: OnChunkEvent<ToolSet>): void;
+    private onRerankOperationEnd;
+    onRerankStart(event: RerankingModelCallStartEvent): void;
+    onRerankEnd(event: RerankingModelCallEndEvent): void;
+    onAbort(event: GenerateTextAbortEvent<ToolSet>): void;
     onError(error: unknown): void;
 }
 
-export { OpenTelemetryIntegration };
+export { type EnrichSpan, LegacyOpenTelemetry, OpenTelemetry, type OpenTelemetryOptions, type OpenTelemetrySpanType };