feat(ai): Expose provider metadata as an attribute on exported OTEL spans (#7096)

## Background

Right now there doesn't appear to be a way for tracing providers to get
accurate metadata if users are using Anthropic/OpenAI/Gemini's prompt
caching features. The tokens used to create/read caches are returned in
a providerMetadata field on the response that does not seem to be passed
anywhere into the exported spans.

## Summary

Adds a new `ai.response.providerMetadata` span attribute that exposes
this response field.

## Verification

Ran `pnpm build` and modified the `anthropic-cache-control.ts` example.
Saw the new span attribute present:

```
{
  resource: {
    attributes: {
      'service.name': 'unknown_service:/usr/local/bin/node',
      'telemetry.sdk.language': 'nodejs',
      'telemetry.sdk.name': 'opentelemetry',
      'telemetry.sdk.version': '2.0.1'
    }
  },
  instrumentationScope: { name: 'ai', version: undefined, schemaUrl: undefined },
  ...
  attributes: {
    'operation.name': 'ai.generateText',
    'ai.operationId': 'ai.generateText',
    'ai.model.provider': 'anthropic.messages',
    'ai.model.id': 'claude-3-5-sonnet-20240620',
    'ai.settings.maxRetries': 2,
    'ai.prompt': `...`,
    'ai.response.providerMetadata': '{"anthropic":{"cacheCreationInputTokens":2157}}',
    'ai.usage.promptTokens': 10,
    'ai.usage.completionTokens': 456
  },
  ...
}
```

## Tasks

- [x] Tests have been added / updated (for bug fixes / features)
- [x] Documentation has been added / updated (for bug fixes / features)
- [x] A _patch_ changeset for relevant packages has been added (for bug
fixes / features - run `pnpm changeset` in the project root)
- [x] Formatting issues have been fixed (run `pnpm prettier-fix` in the
project root)

## Related Issues

Fixes #7079

Author: dancer

.changeset/five-pumpkins-joke.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+Expose provider metadata as an attribute on exported OTEL spans

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

@@ -265,6 +265,7 @@ Many spans that use LLMs (`ai.generateText`, `ai.generateText.doGenerate`, `ai.s
 - `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.response.providerMetadata`: provider specific metadata returned with the generation response
 - `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`
@@ -302,6 +303,7 @@ Many spans that use embedding models (`ai.embed`, `ai.embed.doEmbed`, `ai.embedM
 - `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.response.providerMetadata`: provider specific metadata returned with the generation response
 - `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`

packages/ai/core/generate-object/__snapshots__/generate-object.test.ts.snap

@@ -143,6 +143,7 @@ exports[`telemetry > should record telemetry data when enabled with mode "json"
       "ai.response.id": "test-id-from-model",
       "ai.response.model": "test-response-model-id",
       "ai.response.object": "{ "content": "Hello, world!" }",
+      "ai.response.providerMetadata": "{"testprovider":{"test1":"value1"}}",
       "ai.response.timestamp": "1970-01-01T00:00:10.000Z",
       "ai.settings.frequencyPenalty": 0.3,
       "ai.settings.maxRetries": 2,

packages/ai/core/generate-object/__snapshots__/stream-object.test.ts.snap

@@ -243,6 +243,7 @@ exports[`streamObject > telemetry > should record telemetry data when enabled wi
       "ai.request.headers.header1": "value1",
       "ai.request.headers.header2": "value2",
       "ai.response.object": "{"content":"Hello, world!"}",
+      "ai.response.providerMetadata": "{"testprovider":{"testkey":"testvalue"}}",
       "ai.schema": "{"type":"object","properties":{"content":{"type":"string"}},"required":["content"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}",
       "ai.schema.description": "test description",
       "ai.schema.name": "test-name",
@@ -278,6 +279,7 @@ exports[`streamObject > telemetry > should record telemetry data when enabled wi
       "ai.response.id": "id-0",
       "ai.response.model": "mock-model-id",
       "ai.response.object": "{"content":"Hello, world!"}",
+      "ai.response.providerMetadata": "{"testprovider":{"testkey":"testvalue"}}",
       "ai.response.timestamp": "1970-01-01T00:00:00.000Z",
       "ai.settings.frequencyPenalty": 0.3,
       "ai.settings.maxRetries": 2,

packages/ai/core/generate-object/generate-object.test.ts

@@ -1166,6 +1166,11 @@ describe('telemetry', () => {
             timestamp: new Date(10000),
             modelId: 'test-response-model-id',
           },
+          providerMetadata: {
+            testprovider: {
+              test1: 'value1',
+            },
+          },
         }),
       }),
       schema: z.object({ content: z.string() }),

packages/ai/core/generate-object/generate-object.ts

@@ -572,7 +572,9 @@ export async function generateObject<SCHEMA, RESULT>({
                       'ai.response.model': responseData.modelId,
                       'ai.response.timestamp':
                         responseData.timestamp.toISOString(),
-
+                      'ai.response.providerMetadata': JSON.stringify(
+                        result.providerMetadata,
+                      ),
                       'ai.usage.promptTokens': result.usage.promptTokens,
                       'ai.usage.completionTokens':
                         result.usage.completionTokens,
@@ -698,7 +700,9 @@ export async function generateObject<SCHEMA, RESULT>({
                       'ai.response.model': responseData.modelId,
                       'ai.response.timestamp':
                         responseData.timestamp.toISOString(),
-
+                      'ai.response.providerMetadata': JSON.stringify(
+                        result.providerMetadata,
+                      ),
                       'ai.usage.promptTokens': result.usage.promptTokens,
                       'ai.usage.completionTokens':
                         result.usage.completionTokens,

packages/ai/core/generate-object/stream-object.test.ts

@@ -64,6 +64,11 @@ describe('streamObject', () => {
                     type: 'finish',
                     finishReason: 'stop',
                     usage: { completionTokens: 10, promptTokens: 3 },
+                    providerMetadata: {
+                      testprovider: {
+                        testkey: 'testvalue',
+                      },
+                    },
                   },
                 ]),
                 rawCall: { rawPrompt: 'prompt', rawSettings: {} },
@@ -1944,6 +1949,11 @@ describe('streamObject', () => {
                 type: 'finish',
                 finishReason: 'stop',
                 usage: { completionTokens: 10, promptTokens: 3 },
+                providerMetadata: {
+                  testprovider: {
+                    testkey: 'testvalue',
+                  },
+                },
               },
             ]),
             rawCall: { rawPrompt: 'prompt', rawSettings: {} },

packages/ai/core/generate-object/stream-object.ts

@@ -935,6 +935,8 @@ class DefaultStreamObjectResult<PARTIAL, RESULT, ELEMENT_STREAM>
                         'ai.response.model': response.modelId,
                         'ai.response.timestamp':
                           response.timestamp.toISOString(),
+                        'ai.response.providerMetadata':
+                          JSON.stringify(providerMetadata),
 
                         'ai.usage.promptTokens': finalUsage.promptTokens,
                         'ai.usage.completionTokens':
@@ -965,6 +967,8 @@ class DefaultStreamObjectResult<PARTIAL, RESULT, ELEMENT_STREAM>
                         'ai.response.object': {
                           output: () => JSON.stringify(object),
                         },
+                        'ai.response.providerMetadata':
+                          JSON.stringify(providerMetadata),
                       },
                     }),
                   );

packages/ai/core/generate-text/__snapshots__/generate-text.test.ts.snap

@@ -1745,6 +1745,7 @@ exports[`telemetry > should record telemetry data when enabled 1`] = `
       "ai.request.headers.header1": "value1",
       "ai.request.headers.header2": "value2",
       "ai.response.finishReason": "stop",
+      "ai.response.providerMetadata": "{"testprovider":{"testkey":"testvalue"}}",
       "ai.response.text": "Hello, world!",
       "ai.settings.frequencyPenalty": 0.3,
       "ai.settings.maxRetries": 2,
@@ -1779,6 +1780,7 @@ exports[`telemetry > should record telemetry data when enabled 1`] = `
       "ai.response.finishReason": "stop",
       "ai.response.id": "test-id-from-model",
       "ai.response.model": "test-response-model-id",
+      "ai.response.providerMetadata": "{"testprovider":{"testkey":"testvalue"}}",
       "ai.response.text": "Hello, world!",
       "ai.response.timestamp": "1970-01-01T00:00:10.000Z",
       "ai.settings.frequencyPenalty": 0.3,

packages/ai/core/generate-text/__snapshots__/stream-text.test.ts.snap

@@ -2489,11 +2489,19 @@ exports[`streamText > options.onFinish > should send files 1`] = `
 
 exports[`streamText > options.onFinish > should send sources 1`] = `
 {
-  "experimental_providerMetadata": undefined,
+  "experimental_providerMetadata": {
+    "testprovider": {
+      "testkey": "testvalue",
+    },
+  },
   "files": [],
   "finishReason": "stop",
   "logprobs": undefined,
-  "providerMetadata": undefined,
+  "providerMetadata": {
+    "testprovider": {
+      "testkey": "testvalue",
+    },
+  },
   "reasoning": undefined,
   "reasoningDetails": [],
   "request": {},
@@ -2541,12 +2549,20 @@ exports[`streamText > options.onFinish > should send sources 1`] = `
   ],
   "steps": [
     {
-      "experimental_providerMetadata": undefined,
+      "experimental_providerMetadata": {
+        "testprovider": {
+          "testkey": "testvalue",
+        },
+      },
       "files": [],
       "finishReason": "stop",
       "isContinued": false,
       "logprobs": undefined,
-      "providerMetadata": undefined,
+      "providerMetadata": {
+        "testprovider": {
+          "testkey": "testvalue",
+        },
+      },
       "reasoning": undefined,
       "reasoningDetails": [],
       "request": {},
@@ -3065,6 +3081,7 @@ exports[`streamText > options.transform > with base transformation > telemetry s
       "ai.operationId": "ai.streamText",
       "ai.prompt": "{"prompt":"test-input"}",
       "ai.response.finishReason": "stop",
+      "ai.response.providerMetadata": "{"testProvider":{"testKey":"TEST VALUE"}}",
       "ai.response.text": "HELLO, WORLD!",
       "ai.response.toolCalls": "[{"type":"tool-call","toolCallId":"call-1","toolName":"tool1","args":{"value":"VALUE"}}]",
       "ai.settings.maxRetries": 2,
@@ -3093,6 +3110,7 @@ exports[`streamText > options.transform > with base transformation > telemetry s
       "ai.response.model": "mock-model-id",
       "ai.response.msToFinish": 500,
       "ai.response.msToFirstChunk": 100,
+      "ai.response.providerMetadata": "{"testProvider":{"testKey":"testValue"}}",
       "ai.response.text": "Hello, world!",
       "ai.response.timestamp": "1970-01-01T00:00:00.000Z",
       "ai.response.toolCalls": "[{"type":"tool-call","toolCallId":"call-1","toolName":"tool1","args":{"value":"VALUE"}}]",
@@ -3583,12 +3601,20 @@ exports[`streamText > result.fullStream > should send sources 1`] = `
     "type": "source",
   },
   {
-    "experimental_providerMetadata": undefined,
+    "experimental_providerMetadata": {
+      "testprovider": {
+        "testkey": "testvalue",
+      },
+    },
     "finishReason": "stop",
     "isContinued": false,
     "logprobs": undefined,
     "messageId": "msg-0",
-    "providerMetadata": undefined,
+    "providerMetadata": {
+      "testprovider": {
+        "testkey": "testvalue",
+      },
+    },
     "request": {},
     "response": {
       "headers": undefined,
@@ -3605,10 +3631,18 @@ exports[`streamText > result.fullStream > should send sources 1`] = `
     "warnings": undefined,
   },
   {
-    "experimental_providerMetadata": undefined,
+    "experimental_providerMetadata": {
+      "testprovider": {
+        "testkey": "testvalue",
+      },
+    },
     "finishReason": "stop",
     "logprobs": undefined,
-    "providerMetadata": undefined,
+    "providerMetadata": {
+      "testprovider": {
+        "testkey": "testvalue",
+      },
+    },
     "response": {
       "headers": undefined,
       "id": "id-1",
@@ -4475,12 +4509,20 @@ exports[`streamText > result.steps > should add the reasoning from the model res
 exports[`streamText > result.steps > should add the sources from the model response to the step result 1`] = `
 [
   {
-    "experimental_providerMetadata": undefined,
+    "experimental_providerMetadata": {
+      "testprovider": {
+        "testkey": "testvalue",
+      },
+    },
     "files": [],
     "finishReason": "stop",
     "isContinued": false,
     "logprobs": undefined,
-    "providerMetadata": undefined,
+    "providerMetadata": {
+      "testprovider": {
+        "testkey": "testvalue",
+      },
+    },
     "reasoning": undefined,
     "reasoningDetails": [],
     "request": {},