feat (core): add experimental OpenTelemetry support for generateText and streamText (#1884)

Author: lgrammel

.changeset/new-bugs-admire.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat (core): add experimental OpenTelemetry support for generateText and streamText

content/docs/03-ai-sdk-core/60-telemetry.mdx

@@ -0,0 +1,113 @@
+---
+title: Telemetry
+description: Using OpenTelemetry with AI SDK Core
+---
+
+# Telemetry
+
+<Note type="warning">
+  This feature is experimental and may change in the future. Currently, only the
+  `generateText` and `streamText` functions support telemetry.
+</Note>
+
+The Vercel AI SDK uses [OpenTelemetry](https://opentelemetry.io/) to collect telemetry data.
+OpenTelemetry is an open-source observability framework designed to provide
+standardized instrumentation for collecting telemetry data.
+
+## Enabling telemetry
+
+For Next.js applications, please follow the [Next.js OpenTelemetry guide](https://nextjs.org/docs/app/building-your-application/optimizing/open-telemetry) to enable telemetry first.
+
+You can then use the `experimental_telemetry` option to enable telemetry on specific `streamText` and `generateText` calls while
+the feature is experimental:
+
+```ts highlight="4"
+const result = await generateText({
+  model: openai('gpt-4-turbo'),
+  prompt: 'Write a short story about a cat.',
+  experimental_telemetry: { isEnabled: true },
+});
+```
+
+## Telemetry Metadata
+
+You can provide a `functionId` to identify the function that the telemetry data is for,
+and `metadata` to include additional information in the telemetry data.
+
+```ts highlight="6-10"
+const result = await generateText({
+  model: openai('gpt-4-turbo'),
+  prompt: 'Write a short story about a cat.',
+  experimental_telemetry: {
+    isEnabled: true,
+    functionId: 'my-awesome-function',
+    metadata: {
+      something: 'custom',
+      someOtherThing: 'other-value',
+    },
+  },
+});
+```
+
+## Collected Data
+
+### generateText function
+
+`generateText` records 3 types of spans:
+
+- `ai.generateText`: the full length of the generateText call. It contains 1 or more `ai.generateText.doGenerate` spans.
+  It contains the [basic span information](#basic-span-information) and the following attributes:
+  - `operation.name`: `ai.generateText`
+  - `ai.prompt`: the prompt that was used when calling `generateText`
+  - `ai.settings.maxToolRoundtrips`: the maximum number of tool roundtrips that were set
+- `ai.generateText.doGenerate`: a provider doGenerate call. It can contain `ai.toolCall` spans.
+  It contains the [basic span information](#basic-span-information) and the following attributes:
+  - `operation.name`: `ai.generateText`
+  - `ai.prompt.format`: the format of the prompt
+  - `ai.prompt.messages`: the messages that were passed into the provider
+- `ai.toolCall`: a tool call that is made as part of the generateText call. See [Tool call spans](#tool-call-spans) for more details.
+
+### streamText function
+
+`streamText` records 3 types of spans:
+
+- `ai.streamText`: the full length of the streamText call. It contains a `ai.streamText.doStream` span.
+  It contains the [basic span information](#basic-span-information) and the following attributes:
+  - `operation.name`: `ai.streamText`
+  - `ai.prompt`: the prompt that was used when calling `streamText`
+- `ai.streamText.doStream`: a provider doStream call.
+  This span contains an `ai.stream.firstChunk` event that is emitted when the first chunk of the stream is received.
+  The `doStream` span can also contain `ai.toolCall` spans.
+  It contains the [basic span information](#basic-span-information) and the following attributes:
+  - `operation.name`: `ai.streamText`
+  - `ai.prompt.format`: the format of the prompt
+  - `ai.prompt.messages`: the messages that were passed into the provider
+- `ai.toolCall`: a tool call that is made as part of the generateText call. See [Tool call spans](#tool-call-spans) for more details.
+
+## Span Details
+
+### Basic span information
+
+Many spans (`ai.generateText`, `ai.generateText.doGenerate`, `ai.streamText`, `ai.streamText.doStream`) contain the following attributes:
+
+- `ai.finishReason`: the reason why the generation finished
+- `ai.model.id`: the id of the model
+- `ai.model.provider`: the provider of the model
+- `ai.request.headers.*`: the request headers that were passed in through `headers`
+- `ai.result.text`: the text that was generated
+- `ai.result.toolCalls`: the tool calls that were made as part of the generation (stringified JSON)
+- `ai.settings.maxRetries`: the maximum number of retries that were set
+- `ai.telemetry.functionId`: the functionId that was set through `telemetry.functionId`
+- `ai.telemetry.metadata.*`: the metadata that was passed in through `telemetry.metadata`
+- `ai.usage.completionTokens`: the number of completion tokens that were used
+- `ai.usage.promptTokens`: the number of prompt tokens that were used
+- `resource.name`: the functionId that was set through `telemetry.functionId`
+
+### Tool call spans
+
+Tool call spans (`ai.toolCall`) contain the following attributes:
+
+- `ai.toolCall.name`: the name of the tool
+- `ai.toolCall.id`: the id of the tool call
+- `ai.toolCall.args`: the parameters of the tool call
+- `ai.toolCall.result`: the result of the tool call. Only available if the tool call is successful and the result is serializable.

content/docs/07-reference/ai-sdk-core/01-generate-text.mdx

@@ -337,6 +337,40 @@ console.log(text);
       description:
         'Maximum number of automatic roundtrips for tool calls. An automatic tool call roundtrip is another LLM call with the tool call results when all tool calls of the last assistant message have results. A maximum number is required to prevent infinite loops in the case of misconfigured tools. By default, it is set to 0, which will disable the feature.',
     },
+    {
+      name: 'experimental_telemetry',
+      type: 'TelemetrySettings',
+      isOptional: true,
+      description: 'Telemetry configuration. Experimental feature.',
+      properties: [
+        {
+          type: 'TelemetrySettings',
+          parameters: [
+            {
+              name: 'isEnabled',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable telemetry. Disabled by default while experimental.',
+            },
+            {
+              name: 'functionId',
+              type: 'string',
+              isOptional: true,
+              description:
+                'Identifier for this function. Used to group telemetry data by function.',
+            },
+            {
+              name: 'metadata',
+              isOptional: true,
+              type: 'Record<string, string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>>',
+              description:
+                'Additional information to include in the telemetry data.',
+            },
+          ],
+        },
+      ],
+    },
   ]}
 />
 

content/docs/07-reference/ai-sdk-core/02-stream-text.mdx

@@ -332,6 +332,40 @@ for await (const textPart of textStream) {
       description:
         'Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.',
     },
+    {
+      name: 'experimental_telemetry',
+      type: 'TelemetrySettings',
+      isOptional: true,
+      description: 'Telemetry configuration. Experimental feature.',
+      properties: [
+        {
+          type: 'TelemetrySettings',
+          parameters: [
+            {
+              name: 'isEnabled',
+              type: 'boolean',
+              isOptional: true,
+              description:
+                'Enable or disable telemetry. Disabled by default while experimental.',
+            },
+            {
+              name: 'functionId',
+              type: 'string',
+              isOptional: true,
+              description:
+                'Identifier for this function. Used to group telemetry data by function.',
+            },
+            {
+              name: 'metadata',
+              isOptional: true,
+              type: 'Record<string, string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>>',
+              description:
+                'Additional information to include in the telemetry data.',
+            },
+          ],
+        },
+      ],
+    },
     {
       name: 'onFinish',
       type: '(result: OnFinishResult) => void',

examples/ai-core/package.json

@@ -3,14 +3,17 @@
   "version": "0.0.0",
   "private": true,
   "dependencies": {
+    "@ai-sdk/amazon-bedrock": "latest",
     "@ai-sdk/anthropic": "latest",
     "@ai-sdk/azure": "latest",
     "@ai-sdk/cohere": "latest",
     "@ai-sdk/google": "latest",
     "@ai-sdk/google-vertex": "latest",
     "@ai-sdk/mistral": "latest",
     "@ai-sdk/openai": "latest",
-    "@ai-sdk/amazon-bedrock": "latest",
+    "@opentelemetry/sdk-node": "0.52.0",
+    "@opentelemetry/auto-instrumentations-node": "0.47.0",
+    "@opentelemetry/sdk-trace-node": "1.25.0",
     "ai": "latest",
     "dotenv": "16.4.5",
     "mathjs": "12.4.2",

examples/ai-core/src/telemetry/generate-text-tool-call.ts

@@ -0,0 +1,47 @@
+import { openai } from '@ai-sdk/openai';
+import { generateText, tool } from 'ai';
+import dotenv from 'dotenv';
+import { z } from 'zod';
+import { weatherTool } from '../tools/weather-tool';
+
+dotenv.config();
+
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+const sdk = new NodeSDK({
+  traceExporter: new ConsoleSpanExporter(),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+
+async function main() {
+  const result = await generateText({
+    model: openai('gpt-3.5-turbo'),
+    maxTokens: 512,
+    tools: {
+      weather: weatherTool,
+      cityAttractions: tool({
+        parameters: z.object({ city: z.string() }),
+      }),
+    },
+    prompt:
+      'What is the weather in San Francisco and what attractions should I visit?',
+    experimental_telemetry: {
+      isEnabled: true,
+      functionId: 'my-awesome-function',
+      metadata: {
+        something: 'custom',
+        someOtherThing: 'other-value',
+      },
+    },
+  });
+
+  console.log(JSON.stringify(result, null, 2));
+
+  await sdk.shutdown();
+}
+
+main().catch(console.error);

examples/ai-core/src/telemetry/generate-text.ts

@@ -0,0 +1,38 @@
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+
+const sdk = new NodeSDK({
+  traceExporter: new ConsoleSpanExporter(),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+
+async function main() {
+  const result = await generateText({
+    model: openai('gpt-3.5-turbo'),
+    maxTokens: 50,
+    prompt: 'Invent a new holiday and describe its traditions.',
+    experimental_telemetry: {
+      isEnabled: true,
+      functionId: 'my-awesome-function',
+      metadata: {
+        something: 'custom',
+        someOtherThing: 'other-value',
+      },
+    },
+  });
+
+  console.log(result.text);
+
+  await sdk.shutdown();
+}
+
+main().catch(console.error);

examples/ai-core/src/telemetry/stream-text.ts

@@ -0,0 +1,40 @@
+import { openai } from '@ai-sdk/openai';
+import { streamText } from 'ai';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
+
+const sdk = new NodeSDK({
+  traceExporter: new ConsoleSpanExporter(),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+
+async function main() {
+  const result = await streamText({
+    model: openai('gpt-3.5-turbo'),
+    maxTokens: 50,
+    prompt: 'Invent a new holiday and describe its traditions.',
+    experimental_telemetry: {
+      isEnabled: true,
+      functionId: 'my-awesome-function',
+      metadata: {
+        something: 'custom',
+        someOtherThing: 'other-value',
+      },
+    },
+  });
+
+  for await (const textPart of result.textStream) {
+    process.stdout.write(textPart);
+  }
+
+  await sdk.shutdown();
+}
+
+main().catch(console.error);

examples/next-openai-telemetry/.env.local.example

@@ -0,0 +1 @@
+OPENAI_API_KEY=xxxxxxx

examples/next-openai-telemetry/.gitignore

@@ -0,0 +1,35 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

examples/next-openai-telemetry/app/README.md

@@ -0,0 +1,42 @@
+# Vercel AI SDK, Next.js, and OpenAI Chat Telemetry Example
+
+This example shows how to use the [Vercel AI SDK](https://sdk.vercel.ai/docs) with [Next.js](https://nextjs.org/) and [OpenAI](https://openai.com) to create a ChatGPT-like AI-powered streaming chat bot.
+
+## Deploy your own
+
+Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=ai-sdk-example):
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel%2Fai%2Ftree%2Fmain%2Fexamples%2Fnext-openai-telemetry&env=OPENAI_API_KEY&envDescription=OpenAI%20API%20Key&envLink=https%3A%2F%2Fplatform.openai.com%2Faccount%2Fapi-keys&project-name=vercel-ai-chat-openai-telemetry&repository-name=vercel-ai-chat-openai-telemetry)
+
+## How to use
+
+Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example:
+
+```bash
+npx create-next-app --example https://github.com/vercel/ai/tree/main/examples/next-openai next-openai-app
+```
+
+```bash
+yarn create next-app --example https://github.com/vercel/ai/tree/main/examples/next-openai next-openai-app
+```
+
+```bash
+pnpm create next-app --example https://github.com/vercel/ai/tree/main/examples/next-openai next-openai-app
+```
+
+To run the example locally you need to:
+
+1. Sign up at [OpenAI's Developer Platform](https://platform.openai.com/signup).
+2. Go to [OpenAI's dashboard](https://platform.openai.com/account/api-keys) and create an API KEY.
+3. Set the required OpenAI environment variable as the token value as shown [the example env file](./.env.local.example) but in a new file called `.env.local`
+4. `pnpm install` to install the required dependencies.
+5. `pnpm dev` to launch the development server.
+
+## Learn More
+
+To learn more about OpenAI, Next.js, and the Vercel AI SDK take a look at the following resources:
+
+- [Vercel AI SDK docs](https://sdk.vercel.ai/docs)
+- [Vercel AI Playground](https://play.vercel.ai)
+- [OpenAI Documentation](https://platform.openai.com/docs) - learn about OpenAI features and API.
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.

examples/next-openai-telemetry/app/api/text/route.ts

@@ -0,0 +1,21 @@
+import { openai } from '@ai-sdk/openai';
+import { generateText } from 'ai';
+
+export async function POST(req: Request) {
+  const { prompt } = await req.json();
+
+  const { text } = await generateText({
+    model: openai('gpt-4-turbo'),
+    maxTokens: 100,
+    prompt,
+    experimental_telemetry: {
+      isEnabled: true,
+      functionId: 'example-function-id',
+      metadata: { example: 'value' },
+    },
+  });
+
+  return new Response(JSON.stringify({ text }), {
+    headers: { 'Content-Type': 'application/json' },
+  });
+}

examples/next-openai-telemetry/app/favicon.ico

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

examples/next-openai-telemetry/app/globals.css

@@ -0,0 +1,21 @@
+import './globals.css';
+import { Inter } from 'next/font/google';
+
+const inter = Inter({ subsets: ['latin'] });
+
+export const metadata = {
+  title: 'Vercel AI SDK - Next.js OpenAI Examples',
+  description: 'Examples of using the Vercel AI SDK with Next.js and OpenAI.',
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body className={inter.className}>{children}</body>
+    </html>
+  );
+}

examples/next-openai-telemetry/app/layout.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import { useState } from 'react';
+
+export default function Page() {
+  const [generation, setGeneration] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  return (
+    <div className="flex flex-col items-center justify-center min-h-screen p-4 bg-gray-100">
+      <button
+        className="px-4 py-2 font-bold text-white bg-blue-500 rounded hover:bg-blue-700"
+        onClick={async () => {
+          try {
+            setIsLoading(true);
+
+            const response = await fetch('/api/text', {
+              method: 'POST',
+              body: JSON.stringify({
+                prompt: 'Why is the sky blue?',
+              }),
+              headers: {
+                'Content-Type': 'application/json',
+              },
+            });
+
+            const json = await response.json();
+
+            setGeneration(json.text);
+          } catch (error) {
+            setError(error as Error);
+          } finally {
+            setIsLoading(false);
+          }
+        }}
+      >
+        Generate
+      </button>
+
+      {error && <div className="text-red-500">{error.message}</div>}
+      <div className="mt-4">
+        {isLoading ? (
+          <span className="text-blue-500">Loading...</span>
+        ) : (
+          <span className="text-gray-800">{generation}</span>
+        )}
+      </div>
+    </div>
+  );
+}

examples/next-openai-telemetry/app/page.tsx

@@ -0,0 +1,7 @@
+import { registerOTel } from '@vercel/otel';
+
+export function register() {
+  registerOTel({
+    serviceName: 'next-app',
+  });
+}

examples/next-openai-telemetry/instrumentation.ts

@@ -0,0 +1,8 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {};
+
+nextConfig.experimental = {
+  instrumentationHook: true,
+};
+
+module.exports = nextConfig;

examples/next-openai-telemetry/next.config.js

@@ -0,0 +1,36 @@
+{
+  "name": "next-openai-telemetry",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@ai-sdk/react": "latest",
+    "@opentelemetry/api-logs": "0.52.1",
+    "@opentelemetry/sdk-logs": "0.52.1",
+    "@opentelemetry/instrumentation": "0.52.1",
+    "@vercel/otel": "1.9.1",
+    "ai": "latest",
+    "next": "latest",
+    "openai": "4.47.1",
+    "react": "^18",
+    "react-dom": "^18",
+    "zod": "3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^18",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
+    "autoprefixer": "^10.4.14",
+    "eslint": "^7.32.0",
+    "eslint-config-next": "14.2.3",
+    "postcss": "^8.4.23",
+    "tailwindcss": "^3.3.2",
+    "typescript": "5.1.3"
+  }
+}

examples/next-openai-telemetry/package.json

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

examples/next-openai-telemetry/postcss.config.js

@@ -0,0 +1,18 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './pages/**/*.{js,ts,jsx,tsx,mdx}',
+    './components/**/*.{js,ts,jsx,tsx,mdx}',
+    './app/**/*.{js,ts,jsx,tsx,mdx}',
+  ],
+  theme: {
+    extend: {
+      backgroundImage: {
+        'gradient-radial': 'radial-gradient(var(--tw-gradient-stops))',
+        'gradient-conic':
+          'conic-gradient(from 180deg at 50% 50%, var(--tw-gradient-stops))',
+      },
+    },
+  },
+  plugins: [],
+};

examples/next-openai-telemetry/tailwind.config.js

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

examples/next-openai-telemetry/tsconfig.json

@@ -1,6 +1,8 @@
 import assert from 'node:assert';
 import { z } from 'zod';
+import { setTestTracer } from '../telemetry/get-tracer';
 import { MockLanguageModelV1 } from '../test/mock-language-model-v1';
+import { MockTracer } from '../test/mock-tracer';
 import { generateText } from './generate-text';
 
 const dummyResponseValues = {
@@ -498,3 +500,186 @@ describe('options.headers', () => {
     assert.deepStrictEqual(result.text, 'Hello, world!');
   });
 });
+
+describe('telemetry', () => {
+  let tracer: MockTracer;
+
+  beforeEach(() => {
+    tracer = new MockTracer();
+    setTestTracer(tracer);
+  });
+
+  afterEach(() => {
+    setTestTracer(undefined);
+  });
+
+  it('should not record any telemetry data when not explicitly enabled', async () => {
+    await generateText({
+      model: new MockLanguageModelV1({
+        doGenerate: async ({}) => ({
+          ...dummyResponseValues,
+          text: `Hello, world!`,
+        }),
+      }),
+      prompt: 'prompt',
+    });
+
+    assert.deepStrictEqual(tracer.jsonSpans, []);
+  });
+
+  it('should record telemetry data when enabled', async () => {
+    await generateText({
+      model: new MockLanguageModelV1({
+        doGenerate: async ({}) => ({
+          ...dummyResponseValues,
+          text: `Hello, world!`,
+        }),
+      }),
+      prompt: 'prompt',
+      headers: {
+        header1: 'value1',
+        header2: 'value2',
+      },
+      experimental_telemetry: {
+        isEnabled: true,
+        functionId: 'test-function-id',
+        metadata: {
+          test1: 'value1',
+          test2: false,
+        },
+      },
+    });
+
+    assert.deepStrictEqual(tracer.jsonSpans, [
+      {
+        name: 'ai.generateText',
+        attributes: {
+          'ai.model.id': 'mock-model-id',
+          'ai.model.provider': 'mock-provider',
+          'ai.prompt': '{"prompt":"prompt"}',
+          'ai.settings.maxRetries': undefined,
+          'ai.settings.maxToolRoundtrips': 0,
+          'ai.telemetry.functionId': 'test-function-id',
+          'ai.telemetry.metadata.test1': 'value1',
+          'ai.telemetry.metadata.test2': false,
+          'ai.finishReason': 'stop',
+          'ai.result.text': 'Hello, world!',
+          'ai.result.toolCalls': undefined,
+          'ai.usage.completionTokens': 20,
+          'ai.usage.promptTokens': 10,
+          'ai.request.headers.header1': 'value1',
+          'ai.request.headers.header2': 'value2',
+          'operation.name': 'ai.generateText',
+          'resource.name': 'test-function-id',
+        },
+        events: [],
+      },
+      {
+        name: 'ai.generateText.doGenerate',
+        attributes: {
+          'ai.model.id': 'mock-model-id',
+          'ai.model.provider': 'mock-provider',
+          'ai.prompt.format': 'prompt',
+          'ai.prompt.messages':
+            '[{"role":"user","content":[{"type":"text","text":"prompt"}]}]',
+          'ai.settings.maxRetries': undefined,
+          'ai.telemetry.functionId': 'test-function-id',
+          'ai.telemetry.metadata.test1': 'value1',
+          'ai.telemetry.metadata.test2': false,
+          'ai.finishReason': 'stop',
+          'ai.result.text': 'Hello, world!',
+          'ai.result.toolCalls': undefined,
+          'ai.usage.completionTokens': 20,
+          'ai.usage.promptTokens': 10,
+          'ai.request.headers.header1': 'value1',
+          'ai.request.headers.header2': 'value2',
+          'operation.name': 'ai.generateText',
+          'resource.name': 'test-function-id',
+        },
+        events: [],
+      },
+    ]);
+  });
+
+  it('should record successful tool call', async () => {
+    await generateText({
+      model: new MockLanguageModelV1({
+        doGenerate: async ({}) => ({
+          ...dummyResponseValues,
+          toolCalls: [
+            {
+              toolCallType: 'function',
+              toolCallId: 'call-1',
+              toolName: 'tool1',
+              args: `{ "value": "value" }`,
+            },
+          ],
+        }),
+      }),
+      tools: {
+        tool1: {
+          parameters: z.object({ value: z.string() }),
+          execute: async () => 'result1',
+        },
+      },
+      prompt: 'test-input',
+      experimental_telemetry: {
+        isEnabled: true,
+      },
+    });
+
+    assert.deepStrictEqual(tracer.jsonSpans, [
+      {
+        name: 'ai.generateText',
+        attributes: {
+          'ai.model.id': 'mock-model-id',
+          'ai.model.provider': 'mock-provider',
+          'ai.prompt': '{"prompt":"test-input"}',
+          'ai.settings.maxRetries': undefined,
+          'ai.settings.maxToolRoundtrips': 0,
+          'ai.telemetry.functionId': undefined,
+          'ai.finishReason': 'stop',
+          'ai.result.text': undefined,
+          'ai.result.toolCalls':
+            '[{"toolCallType":"function","toolCallId":"call-1","toolName":"tool1","args":"{ \\"value\\": \\"value\\" }"}]',
+          'ai.usage.completionTokens': 20,
+          'ai.usage.promptTokens': 10,
+          'operation.name': 'ai.generateText',
+          'resource.name': undefined,
+        },
+        events: [],
+      },
+      {
+        name: 'ai.generateText.doGenerate',
+        attributes: {
+          'ai.model.id': 'mock-model-id',
+          'ai.model.provider': 'mock-provider',
+          'ai.prompt.format': 'prompt',
+          'ai.prompt.messages':
+            '[{"role":"user","content":[{"type":"text","text":"test-input"}]}]',
+          'ai.settings.maxRetries': undefined,
+          'ai.telemetry.functionId': undefined,
+          'ai.finishReason': 'stop',
+          'ai.result.text': undefined,
+          'ai.result.toolCalls':
+            '[{"toolCallType":"function","toolCallId":"call-1","toolName":"tool1","args":"{ \\"value\\": \\"value\\" }"}]',
+          'ai.usage.completionTokens': 20,
+          'ai.usage.promptTokens': 10,
+          'operation.name': 'ai.generateText',
+          'resource.name': undefined,
+        },
+        events: [],
+      },
+      {
+        name: 'ai.toolCall',
+        attributes: {
+          'ai.toolCall.name': 'tool1',
+          'ai.toolCall.id': 'call-1',
+          'ai.toolCall.args': '{"value":"value"}',
+          'ai.toolCall.result': '"result1"',
+        },
+        events: [],
+      },
+    ]);
+  });
+});

packages/core/core/generate-text/generate-text.test.ts

@@ -1,3 +1,4 @@
+import { Tracer } from '@opentelemetry/api';
 import { CoreAssistantMessage, CoreToolMessage } from '../prompt';
 import { CallSettings } from '../prompt/call-settings';
 import {
@@ -8,6 +9,10 @@ import { getValidatedPrompt } from '../prompt/get-validated-prompt';
 import { prepareCallSettings } from '../prompt/prepare-call-settings';
 import { prepareToolsAndToolChoice } from '../prompt/prepare-tools-and-tool-choice';
 import { Prompt } from '../prompt/prompt';
+import { getBaseTelemetryAttributes } from '../telemetry/get-base-telemetry-attributes';
+import { getTracer } from '../telemetry/get-tracer';
+import { recordSpan } from '../telemetry/record-span';
+import { TelemetrySettings } from '../telemetry/telemetry-settings';
 import { CoreTool } from '../tool/tool';
 import {
   CallWarning,
@@ -75,6 +80,7 @@ export async function generateText<TOOLS extends Record<string, CoreTool>>({
   headers,
   maxAutomaticRoundtrips = 0,
   maxToolRoundtrips = maxAutomaticRoundtrips,
+  experimental_telemetry: telemetry,
   ...settings
 }: CallSettings &
   Prompt & {
@@ -111,88 +117,162 @@ case of misconfigured tools.
 By default, it's set to 0, which will disable the feature.
      */
     maxToolRoundtrips?: number;
-  }): Promise<GenerateTextResult<TOOLS>> {
-  const retry = retryWithExponentialBackoff({ maxRetries });
-  const validatedPrompt = getValidatedPrompt({ system, prompt, messages });
 
-  const mode = {
-    type: 'regular' as const,
-    ...prepareToolsAndToolChoice({ tools, toolChoice }),
-  };
-  const callSettings = prepareCallSettings(settings);
-  const promptMessages = convertToLanguageModelPrompt(validatedPrompt);
+    /**
+     * Optional telemetry configuration (experimental).
+     */
+    experimental_telemetry?: TelemetrySettings;
+  }): Promise<GenerateTextResult<TOOLS>> {
+  const baseTelemetryAttributes = getBaseTelemetryAttributes({
+    operationName: 'ai.generateText',
+    model,
+    telemetry,
+    headers,
+    settings: { ...settings, maxRetries },
+  });
 
-  let currentModelResponse: Awaited<ReturnType<LanguageModel['doGenerate']>>;
-  let currentToolCalls: ToToolCallArray<TOOLS> = [];
-  let currentToolResults: ToToolResultArray<TOOLS> = [];
-  let roundtrips = 0;
-  const responseMessages: Array<CoreAssistantMessage | CoreToolMessage> = [];
+  const tracer = getTracer({ isEnabled: telemetry?.isEnabled ?? false });
+  return recordSpan({
+    name: 'ai.generateText',
+    attributes: {
+      ...baseTelemetryAttributes,
+      // specific settings that only make sense on the outer level:
+      'ai.prompt': JSON.stringify({ system, prompt, messages }),
+      'ai.settings.maxToolRoundtrips': maxToolRoundtrips,
+    },
+    tracer,
+    fn: async span => {
+      const retry = retryWithExponentialBackoff({ maxRetries });
+      const validatedPrompt = getValidatedPrompt({
+        system,
+        prompt,
+        messages,
+      });
 
-  do {
-    currentModelResponse = await retry(() => {
-      return model.doGenerate({
-        mode,
-        ...callSettings,
+      const mode = {
+        type: 'regular' as const,
+        ...prepareToolsAndToolChoice({ tools, toolChoice }),
+      };
+      const callSettings = prepareCallSettings(settings);
+      const promptMessages = convertToLanguageModelPrompt(validatedPrompt);
+
+      let currentModelResponse: Awaited<
+        ReturnType<LanguageModel['doGenerate']>
+      >;
+      let currentToolCalls: ToToolCallArray<TOOLS> = [];
+      let currentToolResults: ToToolResultArray<TOOLS> = [];
+      let roundtrips = 0;
+      const responseMessages: Array<CoreAssistantMessage | CoreToolMessage> =
+        [];
+
+      do {
         // once we have a roundtrip, we need to switch to messages format:
-        inputFormat: roundtrips === 0 ? validatedPrompt.type : 'messages',
-        prompt: promptMessages,
-        abortSignal,
-        headers,
+        const currentInputFormat =
+          roundtrips === 0 ? validatedPrompt.type : 'messages';
+
+        currentModelResponse = await retry(() =>
+          recordSpan({
+            name: 'ai.generateText.doGenerate',
+            attributes: {
+              ...baseTelemetryAttributes,
+              'ai.prompt.format': currentInputFormat,
+              'ai.prompt.messages': JSON.stringify(promptMessages),
+            },
+            tracer,
+            fn: async span => {
+              const result = await model.doGenerate({
+                mode,
+                ...callSettings,
+                inputFormat: currentInputFormat,
+                prompt: promptMessages,
+                abortSignal,
+                headers,
+              });
+
+              // Add response information to the span:
+              span.setAttributes({
+                'ai.finishReason': result.finishReason,
+                'ai.usage.promptTokens': result.usage.promptTokens,
+                'ai.usage.completionTokens': result.usage.completionTokens,
+                'ai.result.text': result.text,
+                'ai.result.toolCalls': JSON.stringify(result.toolCalls),
+              });
+
+              return result;
+            },
+          }),
+        );
+
+        // parse tool calls:
+        currentToolCalls = (currentModelResponse.toolCalls ?? []).map(
+          modelToolCall => parseToolCall({ toolCall: modelToolCall, tools }),
+        );
+
+        // execute tools:
+        currentToolResults =
+          tools == null
+            ? []
+            : await executeTools({
+                toolCalls: currentToolCalls,
+                tools,
+                tracer,
+              });
+
+        // append to messages for potential next roundtrip:
+        const newResponseMessages = toResponseMessages({
+          text: currentModelResponse.text ?? '',
+          toolCalls: currentToolCalls,
+          toolResults: currentToolResults,
+        });
+        responseMessages.push(...newResponseMessages);
+        promptMessages.push(
+          ...newResponseMessages.map(convertToLanguageModelMessage),
+        );
+      } while (
+        // there are tool calls:
+        currentToolCalls.length > 0 &&
+        // all current tool calls have results:
+        currentToolResults.length === currentToolCalls.length &&
+        // the number of roundtrips is less than the maximum:
+        roundtrips++ < maxToolRoundtrips
+      );
+
+      // Add response information to the span:
+      span.setAttributes({
+        'ai.finishReason': currentModelResponse.finishReason,
+        'ai.usage.promptTokens': currentModelResponse.usage.promptTokens,
+        'ai.usage.completionTokens':
+          currentModelResponse.usage.completionTokens,
+        'ai.result.text': currentModelResponse.text,
+        'ai.result.toolCalls': JSON.stringify(currentModelResponse.toolCalls),
       });
-    });
 
-    // parse tool calls:
-    currentToolCalls = (currentModelResponse.toolCalls ?? []).map(
-      modelToolCall => parseToolCall({ toolCall: modelToolCall, tools }),
-    );
-
-    // execute tools:
-    currentToolResults =
-      tools == null
-        ? []
-        : await executeTools({ toolCalls: currentToolCalls, tools });
-
-    // append to messages for potential next roundtrip:
-    const newResponseMessages = toResponseMessages({
-      text: currentModelResponse.text ?? '',
-      toolCalls: currentToolCalls,
-      toolResults: currentToolResults,
-    });
-    responseMessages.push(...newResponseMessages);
-    promptMessages.push(
-      ...newResponseMessages.map(convertToLanguageModelMessage),
-    );
-  } while (
-    // there are tool calls:
-    currentToolCalls.length > 0 &&
-    // all current tool calls have results:
-    currentToolResults.length === currentToolCalls.length &&
-    // the number of roundtrips is less than the maximum:
-    roundtrips++ < maxToolRoundtrips
-  );
-
-  return new GenerateTextResult({
-    // Always return a string so that the caller doesn't have to check for undefined.
-    // If they need to check if the model did not return any text,
-    // they can check the length of the string:
-    text: currentModelResponse.text ?? '',
-    toolCalls: currentToolCalls,
-    toolResults: currentToolResults,
-    finishReason: currentModelResponse.finishReason,
-    usage: calculateCompletionTokenUsage(currentModelResponse.usage),
-    warnings: currentModelResponse.warnings,
-    rawResponse: currentModelResponse.rawResponse,
-    logprobs: currentModelResponse.logprobs,
-    responseMessages,
+      return new GenerateTextResult({
+        // Always return a string so that the caller doesn't have to check for undefined.
+        // If they need to check if the model did not return any text,
+        // they can check the length of the string:
+        text: currentModelResponse.text ?? '',
+        toolCalls: currentToolCalls,
+        toolResults: currentToolResults,
+        finishReason: currentModelResponse.finishReason,
+        usage: calculateCompletionTokenUsage(currentModelResponse.usage),
+        warnings: currentModelResponse.warnings,
+        rawResponse: currentModelResponse.rawResponse,
+        logprobs: currentModelResponse.logprobs,
+        responseMessages,
+      });
+    },
   });
 }
 
 async function executeTools<TOOLS extends Record<string, CoreTool>>({
   toolCalls,
   tools,
+  tracer,
 }: {
   toolCalls: ToToolCallArray<TOOLS>;
   tools: TOOLS;
+  tracer: Tracer;
 }): Promise<ToToolResultArray<TOOLS>> {
   const toolResults = await Promise.all(
     toolCalls.map(async toolCall => {
@@ -202,7 +282,31 @@ async function executeTools<TOOLS extends Record<string, CoreTool>>({
         return undefined;
       }
 
-      const result = await tool.execute(toolCall.args);
+      const result = await recordSpan({
+        name: 'ai.toolCall',
+        attributes: {
+          'ai.toolCall.name': toolCall.toolName,
+          'ai.toolCall.id': toolCall.toolCallId,
+          'ai.toolCall.args': JSON.stringify(toolCall.args),
+        },
+        tracer,
+        fn: async span => {
+          const result = await tool.execute!(toolCall.args);
+
+          try {
+            span.setAttributes({
+              'ai.toolCall.result': JSON.stringify(result),
+            });
+          } catch (ignored) {
+            // JSON stringify might fail if the result is not serializable,
+            // in which case we just ignore it. In the future we might want to
+            // add an optional serialize method to the tool interface and warn
+            // if the result is not serializable.
+          }
+
+          return result;
+        },
+      });
 
       return {
         toolCallId: toolCall.toolCallId,

packages/core/core/generate-text/generate-text.ts

@@ -1,5 +1,7 @@
 import { LanguageModelV1StreamPart, NoSuchToolError } from '@ai-sdk/provider';
 import { generateId } from '@ai-sdk/ui-utils';
+import { Tracer } from '@opentelemetry/api';
+import { recordSpan } from '../telemetry/record-span';
 import { CoreTool } from '../tool';
 import { calculateCompletionTokenUsage } from '../types/token-usage';
 import { TextStreamPart } from './stream-text';
@@ -8,9 +10,11 @@ import { parseToolCall } from './tool-call';
 export function runToolsTransformation<TOOLS extends Record<string, CoreTool>>({
   tools,
   generatorStream,
+  tracer,
 }: {
   tools?: TOOLS;
   generatorStream: ReadableStream<LanguageModelV1StreamPart>;
+  tracer: Tracer;
 }): ReadableStream<TextStreamPart<TOOLS>> {
   let canClose = false;
   const outstandingToolCalls = new Set<string>();
@@ -82,38 +86,60 @@ export function runToolsTransformation<TOOLS extends Record<string, CoreTool>>({
               const toolExecutionId = generateId(); // use our own id to guarantee uniqueness
               outstandingToolCalls.add(toolExecutionId);
 
-              // Note: we don't await the tool execution here, because we want to process
-              // the next chunk as soon as possible. This is important for the case where
-              // the tool execution takes a long time.
-              tool.execute(toolCall.args).then(
-                (result: any) => {
-                  toolResultsStreamController!.enqueue({
-                    ...toolCall,
-                    type: 'tool-result',
-                    result,
-                  } as any);
-
-                  outstandingToolCalls.delete(toolExecutionId);
-
-                  // close the tool results controller if no more outstanding tool calls
-                  if (canClose && outstandingToolCalls.size === 0) {
-                    toolResultsStreamController!.close();
-                  }
+              // Note: we don't await the tool execution here (by leaving out 'await' on recordSpan),
+              // because we want to process the next chunk as soon as possible.
+              // This is important for the case where the tool execution takes a long time.
+              recordSpan({
+                name: 'ai.toolCall',
+                attributes: {
+                  'ai.toolCall.name': toolCall.toolName,
+                  'ai.toolCall.id': toolCall.toolCallId,
+                  'ai.toolCall.args': JSON.stringify(toolCall.args),
                 },
-                (error: any) => {
-                  toolResultsStreamController!.enqueue({
-                    type: 'error',
-                    error,
-                  });
-
-                  outstandingToolCalls.delete(toolExecutionId);
-
-                  // close the tool results controller if no more outstanding tool calls
-                  if (canClose && outstandingToolCalls.size === 0) {
-                    toolResultsStreamController!.close();
-                  }
-                },
-              );
+                tracer,
+                fn: async span =>
+                  tool.execute!(toolCall.args).then(
+                    (result: any) => {
+                      toolResultsStreamController!.enqueue({
+                        ...toolCall,
+                        type: 'tool-result',
+                        result,
+                      } as any);
+
+                      outstandingToolCalls.delete(toolExecutionId);
+
+                      // close the tool results controller if no more outstanding tool calls
+                      if (canClose && outstandingToolCalls.size === 0) {
+                        toolResultsStreamController!.close();
+                      }
+
+                      // record telemetry
+                      try {
+                        span.setAttributes({
+                          'ai.toolCall.result': JSON.stringify(result),
+                        });
+                      } catch (ignored) {
+                        // JSON stringify might fail if the result is not serializable,
+                        // in which case we just ignore it. In the future we might want to
+                        // add an optional serialize method to the tool interface and warn
+                        // if the result is not serializable.
+                      }
+                    },
+                    (error: any) => {
+                      toolResultsStreamController!.enqueue({
+                        type: 'error',
+                        error,
+                      });
+
+                      outstandingToolCalls.delete(toolExecutionId);
+
+                      // close the tool results controller if no more outstanding tool calls
+                      if (canClose && outstandingToolCalls.size === 0) {
+                        toolResultsStreamController!.close();
+                      }
+                    },
+                  ),
+              });
             }
           } catch (error) {
             toolResultsStreamController!.enqueue({

packages/core/core/generate-text/run-tools-transformation.ts

@@ -9,6 +9,8 @@ import { formatStreamPart } from '../../streams';
 import { MockLanguageModelV1 } from '../test/mock-language-model-v1';
 import { createMockServerResponse } from '../test/mock-server-response';
 import { streamText } from './stream-text';
+import { MockTracer } from '../test/mock-tracer';
+import { setTestTracer } from '../telemetry/get-tracer';
 
 describe('result.textStream', () => {
   it('should send text deltas', async () => {
@@ -1041,3 +1043,220 @@ describe('options.headers', () => {
     );
   });
 });
+
+describe('telemetry', () => {
+  let tracer: MockTracer;
+
+  beforeEach(() => {
+    tracer = new MockTracer();
+    setTestTracer(tracer);
+  });
+
+  afterEach(() => {
+    setTestTracer(undefined);
+  });
+
+  it('should not record any telemetry data when not explicitly enabled', async () => {
+    const result = await streamText({
+      model: new MockLanguageModelV1({
+        doStream: async ({}) => ({
+          stream: convertArrayToReadableStream([
+            { type: 'text-delta', textDelta: 'Hello' },
+            { type: 'text-delta', textDelta: ', ' },
+            { type: 'text-delta', textDelta: `world!` },
+            {
+              type: 'finish',
+              finishReason: 'stop',
+              logprobs: undefined,
+              usage: { completionTokens: 20, promptTokens: 10 },
+            },
+          ]),
+          rawCall: { rawPrompt: 'prompt', rawSettings: {} },
+        }),
+      }),
+      prompt: 'test-input',
+    });
+
+    // consume stream
+    await convertAsyncIterableToArray(result.textStream);
+
+    assert.deepStrictEqual(tracer.jsonSpans, []);
+  });
+
+  it('should record telemetry data when enabled', async () => {
+    const result = await streamText({
+      model: new MockLanguageModelV1({
+        doStream: async ({}) => ({
+          stream: convertArrayToReadableStream([
+            { type: 'text-delta', textDelta: 'Hello' },
+            { type: 'text-delta', textDelta: ', ' },
+            { type: 'text-delta', textDelta: `world!` },
+            {
+              type: 'finish',
+              finishReason: 'stop',
+              logprobs: undefined,
+              usage: { completionTokens: 20, promptTokens: 10 },
+            },
+          ]),
+          rawCall: { rawPrompt: 'prompt', rawSettings: {} },
+        }),
+      }),
+      prompt: 'test-input',
+      headers: {
+        header1: 'value1',
+        header2: 'value2',
+      },
+      experimental_telemetry: {
+        isEnabled: true,
+        functionId: 'test-function-id',
+        metadata: {
+          test1: 'value1',
+          test2: false,
+        },
+      },
+    });
+
+    // consume stream
+    await convertAsyncIterableToArray(result.textStream);
+
+    assert.deepStrictEqual(tracer.jsonSpans, [
+      {
+        name: 'ai.streamText',
+        attributes: {
+          'ai.model.id': 'mock-model-id',
+          'ai.model.provider': 'mock-provider',
+          'ai.prompt': '{"prompt":"test-input"}',
+          'ai.settings.maxRetries': undefined,
+          'ai.telemetry.functionId': 'test-function-id',
+          'ai.telemetry.metadata.test1': 'value1',
+          'ai.telemetry.metadata.test2': false,
+          'ai.finishReason': 'stop',
+          'ai.result.text': 'Hello, world!',
+          'ai.result.toolCalls': undefined,
+          'ai.usage.completionTokens': 20,
+          'ai.usage.promptTokens': 10,
+          'ai.request.headers.header1': 'value1',
+          'ai.request.headers.header2': 'value2',
+          'operation.name': 'ai.streamText',
+          'resource.name': 'test-function-id',
+        },
+        events: [],
+      },
+      {
+        name: 'ai.streamText.doStream',
+        attributes: {
+          'ai.model.id': 'mock-model-id',
+          'ai.model.provider': 'mock-provider',
+          'ai.prompt.format': 'prompt',
+          'ai.prompt.messages':
+            '[{"role":"user","content":[{"type":"text","text":"test-input"}]}]',
+          'ai.settings.maxRetries': undefined,
+          'ai.telemetry.functionId': 'test-function-id',
+          'ai.telemetry.metadata.test1': 'value1',
+          'ai.telemetry.metadata.test2': false,
+          'ai.finishReason': 'stop',
+          'ai.result.text': 'Hello, world!',
+          'ai.result.toolCalls': undefined,
+          'ai.usage.completionTokens': 20,
+          'ai.usage.promptTokens': 10,
+          'ai.request.headers.header1': 'value1',
+          'ai.request.headers.header2': 'value2',
+          'operation.name': 'ai.streamText',
+          'resource.name': 'test-function-id',
+        },
+        events: ['ai.stream.firstChunk'],
+      },
+    ]);
+  });
+
+  it('should record successful tool call', async () => {
+    const result = await streamText({
+      model: new MockLanguageModelV1({
+        doStream: async ({}) => ({
+          stream: convertArrayToReadableStream([
+            {
+              type: 'tool-call',
+              toolCallType: 'function',
+              toolCallId: 'call-1',
+              toolName: 'tool1',
+              args: `{ "value": "value" }`,
+            },
+            {
+              type: 'finish',
+              finishReason: 'stop',
+              logprobs: undefined,
+              usage: { completionTokens: 20, promptTokens: 10 },
+            },
+          ]),
+          rawCall: { rawPrompt: 'prompt', rawSettings: {} },
+        }),
+      }),
+      tools: {
+        tool1: {
+          parameters: z.object({ value: z.string() }),
+          execute: async ({ value }) => `${value}-result`,
+        },
+      },
+      prompt: 'test-input',
+      experimental_telemetry: {
+        isEnabled: true,
+      },
+    });
+
+    // consume stream
+    await convertAsyncIterableToArray(result.textStream);
+
+    assert.deepStrictEqual(tracer.jsonSpans, [
+      {
+        name: 'ai.streamText',
+        attributes: {
+          'ai.model.id': 'mock-model-id',
+          'ai.model.provider': 'mock-provider',
+          'ai.prompt': '{"prompt":"test-input"}',
+          'ai.settings.maxRetries': undefined,
+          'ai.telemetry.functionId': undefined,
+          'ai.finishReason': 'stop',
+          'ai.result.text': '',
+          'ai.result.toolCalls':
+            '[{"type":"tool-call","toolCallId":"call-1","toolName":"tool1","args":{"value":"value"}}]',
+          'ai.usage.completionTokens': 20,
+          'ai.usage.promptTokens': 10,
+          'operation.name': 'ai.streamText',
+          'resource.name': undefined,
+        },
+        events: [],
+      },
+      {
+        name: 'ai.streamText.doStream',
+        attributes: {
+          'ai.model.id': 'mock-model-id',
+          'ai.model.provider': 'mock-provider',
+          'ai.prompt.format': 'prompt',
+          'ai.prompt.messages':
+            '[{"role":"user","content":[{"type":"text","text":"test-input"}]}]',
+          'ai.settings.maxRetries': undefined,
+          'ai.telemetry.functionId': undefined,
+          'ai.finishReason': 'stop',
+          'ai.result.text': '',
+          'ai.result.toolCalls':
+            '[{"type":"tool-call","toolCallId":"call-1","toolName":"tool1","args":{"value":"value"}}]',
+          'ai.usage.completionTokens': 20,
+          'ai.usage.promptTokens': 10,
+          'operation.name': 'ai.streamText',
+          'resource.name': undefined,
+        },
+        events: ['ai.stream.firstChunk'],
+      },
+      {
+        name: 'ai.toolCall',
+        attributes: {
+          'ai.toolCall.name': 'tool1',
+          'ai.toolCall.id': 'call-1',
+          'ai.toolCall.args': '{"value":"value"}',
+          'ai.toolCall.result': '"value-result"',
+        },
+        events: [],
+      },
+    ]);
+  });
+});

packages/core/core/generate-text/stream-text.test.ts

@@ -1,3 +1,4 @@
+import { Span } from '@opentelemetry/api';
 import { ServerResponse } from 'node:http';
 import {
   AIStreamCallbacksAndOptions,
@@ -10,6 +11,10 @@ import { getValidatedPrompt } from '../prompt/get-validated-prompt';
 import { prepareCallSettings } from '../prompt/prepare-call-settings';
 import { prepareToolsAndToolChoice } from '../prompt/prepare-tools-and-tool-choice';
 import { Prompt } from '../prompt/prompt';
+import { getBaseTelemetryAttributes } from '../telemetry/get-base-telemetry-attributes';
+import { getTracer } from '../telemetry/get-tracer';
+import { recordSpan } from '../telemetry/record-span';
+import { TelemetrySettings } from '../telemetry/telemetry-settings';
 import { CoreTool } from '../tool';
 import {
   CallWarning,
@@ -77,6 +82,7 @@ export async function streamText<TOOLS extends Record<string, CoreTool>>({
   maxRetries,
   abortSignal,
   headers,
+  experimental_telemetry: telemetry,
   onFinish,
   ...settings
 }: CallSettings &
@@ -96,6 +102,11 @@ The tool choice strategy. Default: 'auto'.
      */
     toolChoice?: CoreToolChoice<TOOLS>;
 
+    /**
+     * Optional telemetry configuration (experimental).
+     */
+    experimental_telemetry?: TelemetrySettings;
+
     /**
 Callback that is called when the LLM response and all request tool executions 
 (for tools that have an `execute` function) are finished.
@@ -142,30 +153,74 @@ Warnings from the model provider (e.g. unsupported settings).
       warnings?: CallWarning[];
     }) => Promise<void> | void;
   }): Promise<StreamTextResult<TOOLS>> {
-  const retry = retryWithExponentialBackoff({ maxRetries });
-  const validatedPrompt = getValidatedPrompt({ system, prompt, messages });
-  const { stream, warnings, rawResponse } = await retry(() =>
-    model.doStream({
-      mode: {
-        type: 'regular',
-        ...prepareToolsAndToolChoice({ tools, toolChoice }),
-      },
-      ...prepareCallSettings(settings),
-      inputFormat: validatedPrompt.type,
-      prompt: convertToLanguageModelPrompt(validatedPrompt),
-      abortSignal,
-      headers,
-    }),
-  );
-
-  return new StreamTextResult({
-    stream: runToolsTransformation({
-      tools,
-      generatorStream: stream,
-    }),
-    warnings,
-    rawResponse,
-    onFinish,
+  const baseTelemetryAttributes = getBaseTelemetryAttributes({
+    operationName: 'ai.streamText',
+    model,
+    telemetry,
+    headers,
+    settings: { ...settings, maxRetries },
+  });
+
+  const tracer = getTracer({ isEnabled: telemetry?.isEnabled ?? false });
+
+  return recordSpan({
+    name: 'ai.streamText',
+    attributes: {
+      ...baseTelemetryAttributes,
+      // specific settings that only make sense on the outer level:
+      'ai.prompt': JSON.stringify({ system, prompt, messages }),
+    },
+    tracer,
+    endWhenDone: false,
+    fn: async rootSpan => {
+      const retry = retryWithExponentialBackoff({ maxRetries });
+      const validatedPrompt = getValidatedPrompt({ system, prompt, messages });
+      const promptMessages = convertToLanguageModelPrompt(validatedPrompt);
+      const {
+        result: { stream, warnings, rawResponse },
+        doStreamSpan,
+      } = await retry(() =>
+        recordSpan({
+          name: 'ai.streamText.doStream',
+          attributes: {
+            ...baseTelemetryAttributes,
+            'ai.prompt.format': validatedPrompt.type,
+            'ai.prompt.messages': JSON.stringify(promptMessages),
+          },
+          tracer,
+          endWhenDone: false,
+          fn: async doStreamSpan => {
+            return {
+              result: await model.doStream({
+                mode: {
+                  type: 'regular',
+                  ...prepareToolsAndToolChoice({ tools, toolChoice }),
+                },
+                ...prepareCallSettings(settings),
+                inputFormat: validatedPrompt.type,
+                prompt: promptMessages,
+                abortSignal,
+                headers,
+              }),
+              doStreamSpan,
+            };
+          },
+        }),
+      );
+
+      return new StreamTextResult({
+        stream: runToolsTransformation({
+          tools,
+          generatorStream: stream,
+          tracer,
+        }),
+        warnings,
+        rawResponse,
+        onFinish,
+        rootSpan,
+        doStreamSpan,
+      });
+    },
   });
 }
 
@@ -247,13 +302,17 @@ Response headers.
     warnings,
     rawResponse,
     onFinish,
+    rootSpan,
+    doStreamSpan,
   }: {
     stream: ReadableStream<TextStreamPart<TOOLS>>;
     warnings: CallWarning[] | undefined;
     rawResponse?: {
       headers?: Record<string, string>;
     };
     onFinish?: Parameters<typeof streamText>[0]['onFinish'];
+    rootSpan: Span;
+    doStreamSpan: Span;
   }) {
     this.warnings = warnings;
     this.rawResponse = rawResponse;
@@ -303,6 +362,7 @@ Response headers.
     let text = '';
     const toolCalls: ToToolCall<TOOLS>[] = [];
     const toolResults: ToToolResult<TOOLS>[] = [];
+    let firstChunk = true;
 
     // pipe chunks through a transformation stream that extracts metadata:
     const self = this;
@@ -311,49 +371,92 @@ Response headers.
         async transform(chunk, controller): Promise<void> {
           controller.enqueue(chunk);
 
-          // Create the full text from text deltas (for onFinish callback and text promise):
-          if (chunk.type === 'text-delta') {
-            text += chunk.textDelta;
+          // Telemetry event for first chunk:
+          if (firstChunk) {
+            firstChunk = false;
+            doStreamSpan.addEvent('ai.stream.firstChunk');
           }
 
-          // store tool calls for onFinish callback and toolCalls promise:
-          if (chunk.type === 'tool-call') {
-            toolCalls.push(chunk);
-          }
-
-          // store tool results for onFinish callback and toolResults promise:
-          if (chunk.type === 'tool-result') {
-            toolResults.push(chunk);
-          }
-
-          // Note: tool executions might not be finished yet when the finish event is emitted.
-          if (chunk.type === 'finish') {
-            // store usage and finish reason for promises and onFinish callback:
-            usage = chunk.usage;
-            finishReason = chunk.finishReason;
-
-            // resolve promises that can be resolved now:
-            resolveUsage(usage);
-            resolveFinishReason(finishReason);
-            resolveText(text);
-            resolveToolCalls(toolCalls);
+          const chunkType = chunk.type;
+          switch (chunkType) {
+            case 'text-delta':
+              // create the full text from text deltas (for onFinish callback and text promise):
+              text += chunk.textDelta;
+              break;
+
+            case 'tool-call':
+              // store tool calls for onFinish callback and toolCalls promise:
+              toolCalls.push(chunk);
+              break;
+
+            case 'tool-result':
+              // store tool results for onFinish callback and toolResults promise:
+              toolResults.push(chunk);
+              break;
+
+            case 'finish':
+              // Note: tool executions might not be finished yet when the finish event is emitted.
+              // store usage and finish reason for promises and onFinish callback:
+              usage = chunk.usage;
+              finishReason = chunk.finishReason;
+
+              // resolve promises that can be resolved now:
+              resolveUsage(usage);
+              resolveFinishReason(finishReason);
+              resolveText(text);
+              resolveToolCalls(toolCalls);
+              break;
+
+            case 'error':
+              // ignored
+              break;
+
+            default: {
+              const exhaustiveCheck: never = chunkType;
+              throw new Error(`Unknown chunk type: ${exhaustiveCheck}`);
+            }
           }
         },
 
         // invoke onFinish callback and resolve toolResults promise when the stream is about to close:
         async flush(controller) {
           try {
+            const finalUsage = usage ?? {
+              promptTokens: NaN,
+              completionTokens: NaN,
+              totalTokens: NaN,
+            };
+            const finalFinishReason = finishReason ?? 'unknown';
+            const telemetryToolCalls =
+              toolCalls.length > 0 ? JSON.stringify(toolCalls) : undefined;
+
+            doStreamSpan.setAttributes({
+              'ai.finishReason': finalFinishReason,
+              'ai.usage.promptTokens': finalUsage.promptTokens,
+              'ai.usage.completionTokens': finalUsage.completionTokens,
+              'ai.result.text': text,
+              'ai.result.toolCalls': telemetryToolCalls,
+            });
+
+            // finish doStreamSpan before other operations for correct timing:
+            doStreamSpan.end();
+
+            // Add response information to the root span:
+            rootSpan.setAttributes({
+              'ai.finishReason': finalFinishReason,
+              'ai.usage.promptTokens': finalUsage.promptTokens,
+              'ai.usage.completionTokens': finalUsage.completionTokens,
+              'ai.result.text': text,
+              'ai.result.toolCalls': telemetryToolCalls,
+            });
+
             // resolve toolResults promise:
             resolveToolResults(toolResults);
 
             // call onFinish callback:
             await self.onFinish?.({
-              finishReason: finishReason ?? 'unknown',
-              usage: usage ?? {
-                promptTokens: NaN,
-                completionTokens: NaN,
-                totalTokens: NaN,
-              },
+              finishReason: finalFinishReason,
+              usage: finalUsage,
               text,
               toolCalls,
               // The tool results are inferred as a never[] type, because they are
@@ -366,6 +469,8 @@ Response headers.
             });
           } catch (error) {
             controller.error(error);
+          } finally {
+            rootSpan.end();
           }
         },
       }),

packages/core/core/generate-text/stream-text.ts

@@ -0,0 +1,51 @@
+import { Attributes } from '@opentelemetry/api';
+import { CallSettings } from '../prompt/call-settings';
+import { LanguageModel } from '../types/language-model';
+import { TelemetrySettings } from './telemetry-settings';
+
+export function getBaseTelemetryAttributes({
+  operationName,
+  model,
+  settings,
+  telemetry,
+  headers,
+}: {
+  operationName: string;
+  model: LanguageModel;
+  settings: Omit<CallSettings, 'abortSignal' | 'headers'>;
+  telemetry: TelemetrySettings | undefined;
+  headers: Record<string, string | undefined> | undefined;
+}): Attributes {
+  return {
+    'ai.model.provider': model.provider,
+    'ai.model.id': model.modelId,
+
+    // settings:
+    ...Object.entries(settings).reduce((attributes, [key, value]) => {
+      attributes[`ai.settings.${key}`] = value;
+      return attributes;
+    }, {} as Attributes),
+
+    // special telemetry information
+    'operation.name': operationName,
+    'resource.name': telemetry?.functionId,
+    'ai.telemetry.functionId': telemetry?.functionId,
+
+    // add metadata as attributes:
+    ...Object.entries(telemetry?.metadata ?? {}).reduce(
+      (attributes, [key, value]) => {
+        attributes[`ai.telemetry.metadata.${key}`] = value;
+        return attributes;
+      },
+      {} as Attributes,
+    ),
+
+    // request headers
+    ...Object.entries(headers ?? {}).reduce((attributes, [key, value]) => {
+      if (value !== undefined) {
+        attributes[`ai.request.headers.${key}`] = value;
+      }
+      return attributes;
+    }, {} as Attributes),
+  };
+}

packages/core/core/telemetry/get-base-telemetry-attributes.ts

@@ -0,0 +1,23 @@
+import { Tracer, trace } from '@opentelemetry/api';
+import { noopTracer } from './noop-tracer';
+
+/**
+ * Tracer variable for testing. Tests can set this to a mock tracer.
+ */
+let testTracer: Tracer | undefined = undefined;
+
+export function setTestTracer(tracer: Tracer | undefined) {
+  testTracer = tracer;
+}
+
+export function getTracer({ isEnabled }: { isEnabled: boolean }): Tracer {
+  if (!isEnabled) {
+    return noopTracer;
+  }
+
+  if (testTracer) {
+    return testTracer;
+  }
+
+  return trace.getTracer('ai');
+}

packages/core/core/telemetry/get-tracer.ts

@@ -0,0 +1,69 @@
+import { Span, SpanContext, Tracer } from '@opentelemetry/api';
+
+/**
+ * Tracer implementation that does nothing (null object).
+ */
+export const noopTracer: Tracer = {
+  startSpan(): Span {
+    return noopSpan;
+  },
+
+  startActiveSpan<F extends (span: Span) => unknown>(
+    name: unknown,
+    arg1: unknown,
+    arg2?: unknown,
+    arg3?: F,
+  ): ReturnType<any> {
+    if (typeof arg1 === 'function') {
+      return arg1(noopSpan);
+    }
+    if (typeof arg2 === 'function') {
+      return arg2(noopSpan);
+    }
+    if (typeof arg3 === 'function') {
+      return arg3(noopSpan);
+    }
+  },
+};
+
+const noopSpan: Span = {
+  spanContext() {
+    return noopSpanContext;
+  },
+  setAttribute() {
+    return this;
+  },
+  setAttributes() {
+    return this;
+  },
+  addEvent() {
+    return this;
+  },
+  addLink() {
+    return this;
+  },
+  addLinks() {
+    return this;
+  },
+  setStatus() {
+    return this;
+  },
+  updateName() {
+    return this;
+  },
+  end() {
+    return this;
+  },
+  isRecording() {
+    return false;
+  },
+  recordException() {
+    return this;
+  },
+};
+
+const noopSpanContext: SpanContext = {
+  traceId: '',
+  spanId: '',
+  traceFlags: 0,
+};

packages/core/core/telemetry/noop-tracer.ts

@@ -0,0 +1,48 @@
+import { Attributes, Span, Tracer, SpanStatusCode } from '@opentelemetry/api';
+
+export function recordSpan<T>({
+  name,
+  tracer,
+  attributes,
+  fn,
+  endWhenDone = true,
+}: {
+  name: string;
+  tracer: Tracer;
+  attributes: Attributes;
+  fn: (span: Span) => Promise<T>;
+  endWhenDone?: boolean;
+}) {
+  return tracer.startActiveSpan(name, { attributes }, async span => {
+    try {
+      const result = await fn(span);
+
+      if (endWhenDone) {
+        span.end();
+      }
+
+      return result;
+    } catch (error) {
+      try {
+        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 });
+        }
+      } finally {
+        // always stop the span when there is an error:
+        span.end();
+      }
+
+      throw error;
+    }
+  });
+}

packages/core/core/telemetry/record-span.ts

@@ -0,0 +1,23 @@
+import { AttributeValue } from '@opentelemetry/api';
+
+/**
+ * Telemetry configuration.
+ */
+// This is meant to be both flexible for custom app requirements (metadata)
+// and extensible for standardization (example: functionId, more to come).
+export type TelemetrySettings = {
+  /**
+   * Enable or disable telemetry. Disabled by default while experimental.
+   */
+  isEnabled?: boolean;
+
+  /**
+   * Identifier for this function. Used to group telemetry data by function.
+   */
+  functionId?: string;
+
+  /**
+   * Additional information to include in the telemetry data.
+   */
+  metadata?: Record<string, AttributeValue>;
+};

packages/core/core/telemetry/telemetry-settings.ts

@@ -0,0 +1,134 @@
+import {
+  AttributeValue,
+  Attributes,
+  Context,
+  Span,
+  SpanContext,
+  SpanOptions,
+  Tracer,
+} from '@opentelemetry/api';
+
+export class MockTracer implements Tracer {
+  spans: MockSpan[] = [];
+
+  get jsonSpans() {
+    return this.spans.map(span => ({
+      name: span.name,
+      attributes: span.attributes,
+      events: span.events,
+    }));
+  }
+
+  startSpan(name: string, options?: SpanOptions, context?: Context): Span {
+    const span = new MockSpan({
+      name,
+      options,
+      context,
+    });
+    this.spans.push(span);
+    return span;
+  }
+
+  startActiveSpan<F extends (span: Span) => unknown>(
+    name: string,
+    arg1: unknown,
+    arg2?: unknown,
+    arg3?: F,
+  ): ReturnType<any> {
+    if (typeof arg1 === 'function') {
+      const span = new MockSpan({
+        name,
+      });
+      this.spans.push(span);
+      return arg1(span);
+    }
+    if (typeof arg2 === 'function') {
+      const span = new MockSpan({
+        name,
+        options: arg1 as SpanOptions,
+      });
+      this.spans.push(span);
+      return arg2(span);
+    }
+    if (typeof arg3 === 'function') {
+      const span = new MockSpan({
+        name,
+        options: arg1 as SpanOptions,
+        context: arg2 as Context,
+      });
+      this.spans.push(span);
+      return arg3(span);
+    }
+  }
+}
+
+class MockSpan implements Span {
+  name: string;
+  context?: Context;
+  options?: SpanOptions;
+  attributes: Attributes;
+  events: string[] = [];
+
+  readonly _spanContext: SpanContext = new MockSpanContext();
+
+  constructor({
+    name,
+    options,
+    context,
+  }: {
+    name: string;
+    options?: SpanOptions;
+    context?: Context;
+  }) {
+    this.name = name;
+    this.context = context;
+    this.options = options;
+    this.attributes = options?.attributes ?? {};
+  }
+
+  spanContext(): SpanContext {
+    return this._spanContext;
+  }
+
+  setAttribute(key: string, value: AttributeValue): this {
+    this.attributes = { ...this.attributes, [key]: value };
+    return this;
+  }
+
+  setAttributes(attributes: Attributes): this {
+    this.attributes = { ...this.attributes, ...attributes };
+    return this;
+  }
+
+  addEvent(name: string): this {
+    this.events.push(name);
+    return this;
+  }
+  addLink() {
+    return this;
+  }
+  addLinks() {
+    return this;
+  }
+  setStatus() {
+    return this;
+  }
+  updateName() {
+    return this;
+  }
+  end() {
+    return this;
+  }
+  isRecording() {
+    return false;
+  }
+  recordException() {
+    return this;
+  }
+}
+
+class MockSpanContext implements SpanContext {
+  traceId = 'test-trace-id';
+  spanId = 'test-span-id';
+  traceFlags = 0;
+}

packages/core/core/test/mock-tracer.ts

@@ -82,6 +82,7 @@
     "@ai-sdk/svelte": "0.0.14",
     "@ai-sdk/ui-utils": "0.0.11",
     "@ai-sdk/vue": "0.0.13",
+    "@opentelemetry/api": "1.9.0",
     "eventsource-parser": "1.1.2",
     "jsondiffpatch": "0.6.0",
     "json-schema": "0.4.0",