feat (ai): expose response id, response model, response timestamp in telemetry and api (#2893)

Author: lgrammel

.changeset/calm-walls-sin.md

@@ -0,0 +1,11 @@
+---
+'@ai-sdk/provider-utils': patch
+'@ai-sdk/anthropic': patch
+'@ai-sdk/provider': patch
+'@ai-sdk/mistral': patch
+'@ai-sdk/cohere': patch
+'@ai-sdk/openai': patch
+'ai': patch
+---
+
+feat (ai): expose response id, response model, response timestamp in telemetry and api

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

@@ -61,41 +61,47 @@ const result = await generateText({
 
 `generateText` records 3 types of spans:
 
-- `ai.generateText`: the full length of the generateText call. It contains 1 or more `ai.generateText.doGenerate` spans.
+- `ai.generateText` (span): the full length of the generateText call. It contains 1 or more `ai.generateText.doGenerate` spans.
   It contains the [basic LLM span information](#basic-llm-span-information) and the following attributes:
+
   - `operation.name`: `ai.generateText` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.generateText"`
   - `ai.prompt`: the prompt that was used when calling `generateText`
   - `ai.response.text`: the text that was generated
   - `ai.response.toolCalls`: the tool calls that were made as part of the generation (stringified JSON)
   - `ai.response.finishReason`: the reason why the generation finished
   - `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 LLM span information](#basic-llm-span-information) and the following attributes:
+
+- `ai.generateText.doGenerate` (span): a provider doGenerate call. It can contain `ai.toolCall` spans.
+  It contains the [call LLM span information](#call-llm-span-information) and the following attributes:
+
   - `operation.name`: `ai.generateText.doGenerate` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.generateText.doGenerate"`
   - `ai.prompt.format`: the format of the prompt
   - `ai.prompt.messages`: the messages that were passed into the provider
   - `ai.response.text`: the text that was generated
   - `ai.response.toolCalls`: the tool calls that were made as part of the generation (stringified JSON)
   - `ai.response.finishReason`: the reason why the generation finished
-- `ai.toolCall`: a tool call that is made as part of the generateText call. See [Tool call spans](#tool-call-spans) for more details.
+
+- `ai.toolCall` (span): 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:
+`streamText` records 3 types of spans and 2 types of events:
 
-- `ai.streamText`: the full length of the streamText call. It contains a `ai.streamText.doStream` span.
+- `ai.streamText` (span): the full length of the streamText call. It contains a `ai.streamText.doStream` span.
   It contains the [basic LLM span information](#basic-llm-span-information) and the following attributes:
+
   - `operation.name`: `ai.streamText` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.streamText"`
   - `ai.prompt`: the prompt that was used when calling `streamText`
   - `ai.response.text`: the text that was generated
   - `ai.response.toolCalls`: the tool calls that were made as part of the generation (stringified JSON)
   - `ai.response.finishReason`: the reason why the generation finished
-- `ai.streamText.doStream`: a provider doStream call.
+
+- `ai.streamText.doStream` (span): a provider doStream call.
   This span contains an `ai.stream.firstChunk` event and `ai.toolCall` spans.
-  It contains the [basic LLM span information](#basic-llm-span-information) and the following attributes:
+  It contains the [call LLM span information](#call-llm-span-information) and the following attributes:
 
   - `operation.name`: `ai.streamText.doStream` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.streamText.doStream"`
@@ -108,19 +114,23 @@ const result = await generateText({
   - `ai.response.avgCompletionTokensPerSecond`: the average number of completion tokens per second
   - `ai.response.finishReason`: the reason why the generation finished
 
+- `ai.toolCall` (span): a tool call that is made as part of the generateText call. See [Tool call spans](#tool-call-spans) for more details.
+
 - `ai.stream.firstChunk` (event): an event that is emitted when the first chunk of the stream is received.
+
   - `ai.response.msToFirstChunk`: the time it took to receive the first chunk
+
 - `ai.stream.finish` (event): an event that is emitted when the finish part of the LLM stream is received.
-- `ai.toolCall`: a tool call that is made as part of the generateText call. See [Tool call spans](#tool-call-spans) for more details.
 
 It also records a `ai.stream.firstChunk` event when the first chunk of the stream is received.
 
 ### generateObject function
 
 `generateObject` records 2 types of spans:
 
-- `ai.generateObject`: the full length of the generateObject call. It contains 1 or more `ai.generateObject.doGenerate` spans.
+- `ai.generateObject` (span): the full length of the generateObject call. It contains 1 or more `ai.generateObject.doGenerate` spans.
   It contains the [basic LLM span information](#basic-llm-span-information) and the following attributes:
+
   - `operation.name`: `ai.generateObject` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.generateObject"`
   - `ai.prompt`: the prompt that was used when calling `generateObject`
@@ -130,8 +140,10 @@ It also records a `ai.stream.firstChunk` event when the first chunk of the strea
   - `ai.response.object`: the object that was generated (stringified JSON)
   - `ai.settings.mode`: the object generation mode, e.g. `json`
   - `ai.settings.output`: the output type that was used, e.g. `object` or `no-schema`
-- `ai.generateObject.doGenerate`: a provider doGenerate call.
-  It contains the [basic LLM span information](#basic-llm-span-information) and the following attributes:
+
+- `ai.generateObject.doGenerate` (span): a provider doGenerate call.
+  It contains the [call LLM span information](#call-llm-span-information) and the following attributes:
+
   - `operation.name`: `ai.generateObject.doGenerate` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.generateObject.doGenerate"`
   - `ai.prompt.format`: the format of the prompt
@@ -142,10 +154,11 @@ It also records a `ai.stream.firstChunk` event when the first chunk of the strea
 
 ### streamObject function
 
-`streamObject` records 2 types of spans:
+`streamObject` records 2 types of spans and 1 type of event:
 
-- `ai.streamObject`: the full length of the streamObject call. It contains 1 or more `ai.streamObject.doStream` spans.
+- `ai.streamObject` (span): the full length of the streamObject call. It contains 1 or more `ai.streamObject.doStream` spans.
   It contains the [basic LLM span information](#basic-llm-span-information) and the following attributes:
+
   - `operation.name`: `ai.streamObject` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.streamObject"`
   - `ai.prompt`: the prompt that was used when calling `streamObject`
@@ -155,9 +168,11 @@ It also records a `ai.stream.firstChunk` event when the first chunk of the strea
   - `ai.response.object`: the object that was generated (stringified JSON)
   - `ai.settings.mode`: the object generation mode, e.g. `json`
   - `ai.settings.output`: the output type that was used, e.g. `object` or `no-schema`
-- `ai.streamObject.doStream`: a provider doStream call.
+
+- `ai.streamObject.doStream` (span): a provider doStream call.
   This span contains an `ai.stream.firstChunk` event.
-  It contains the [basic LLM span information](#basic-llm-span-information) and the following attributes:
+  It contains the [call LLM span information](#call-llm-span-information) and the following attributes:
+
   - `operation.name`: `ai.streamObject.doStream` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.streamObject.doStream"`
   - `ai.prompt.format`: the format of the prompt
@@ -166,21 +181,25 @@ It also records a `ai.stream.firstChunk` event when the first chunk of the strea
   - `ai.response.object`: the object that was generated (stringified JSON)
   - `ai.response.msToFirstChunk`: the time it took to receive the first chunk
   - `ai.response.finishReason`: the reason why the generation finished
+
 - `ai.stream.firstChunk` (event): an event that is emitted when the first chunk of the stream is received.
   - `ai.response.msToFirstChunk`: the time it took to receive the first chunk
 
 ### embed function
 
 `embed` records 2 types of spans:
 
-- `ai.embed`: the full length of the embed call. It contains 1 `ai.embed.doEmbed` spans.
+- `ai.embed` (span): the full length of the embed call. It contains 1 `ai.embed.doEmbed` spans.
   It contains the [basic embedding span information](#basic-embedding-span-information) and the following attributes:
+
   - `operation.name`: `ai.embed` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.embed"`
   - `ai.value`: the value that was passed into the `embed` function
   - `ai.embedding`: a JSON-stringified embedding
-- `ai.embed.doEmbed`: a provider doEmbed call.
+
+- `ai.embed.doEmbed` (span): a provider doEmbed call.
   It contains the [basic embedding span information](#basic-embedding-span-information) and the following attributes:
+
   - `operation.name`: `ai.embed.doEmbed` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.embed.doEmbed"`
   - `ai.values`: the values that were passed into the provider (array)
@@ -190,14 +209,17 @@ It also records a `ai.stream.firstChunk` event when the first chunk of the strea
 
 `embedMany` records 2 types of spans:
 
-- `ai.embedMany`: the full length of the embedMany call. It contains 1 or more `ai.embedMany.doEmbed` spans.
+- `ai.embedMany` (span): the full length of the embedMany call. It contains 1 or more `ai.embedMany.doEmbed` spans.
   It contains the [basic embedding span information](#basic-embedding-span-information) and the following attributes:
+
   - `operation.name`: `ai.embedMany` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.embedMany"`
   - `ai.values`: the values that were passed into the `embedMany` function
   - `ai.embeddings`: an array of JSON-stringified embedding
-- `ai.embedMany.doEmbed`: a provider doEmbed call.
+
+- `ai.embedMany.doEmbed` (span): a provider doEmbed call.
   It contains the [basic embedding span information](#basic-embedding-span-information) and the following attributes:
+
   - `operation.name`: `ai.embedMany.doEmbed` and the functionId that was set through `telemetry.functionId`
   - `ai.operationId`: `"ai.embedMany.doEmbed"`
   - `ai.values`: the values that were sent to the provider
@@ -219,6 +241,15 @@ Many spans that use LLMs (`ai.generateText`, `ai.generateText.doGenerate`, `ai.s
 - `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
+
+### Call LLM span information
+
+Spans that correspond to individual LLM calls (`ai.generateText.doGenerate`, `ai.streamText.doStream`, `ai.generateObject.doGenerate`, `ai.streamObject.doStream`) contain
+[basic LLM span information](#basic-llm-span-information) and the following attributes:
+
+- `ai.response.model`: the model that was used to generate the response. This can be different from the model that was requested if the provider supports aliases.
+- `ai.response.id`: the id of the response. Uses the ID from the provider when available.
+- `ai.response.timestamp`: the timestamp of the response. Uses the timestamp from the provider when available.
 - [Semantic Conventions for GenAI operations](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/)
   - `gen_ai.system`: the provider that was used
   - `gen_ai.request.model`: the model that was requested
@@ -230,6 +261,8 @@ Many spans that use LLMs (`ai.generateText`, `ai.generateText.doGenerate`, `ai.s
   - `gen_ai.request.top_p`: the topP parameter value that was set
   - `gen_ai.request.stop_sequences`: the stop sequences
   - `gen_ai.response.finish_reasons`: the finish reasons that were returned by the provider
+  - `gen_ai.response.model`: the model that was used to generate the response. This can be different from the model that was requested if the provider supports aliases.
+  - `gen_ai.response.id`: the id of the response. Uses the ID from the provider when available.
   - `gen_ai.usage.input_tokens`: the number of prompt tokens that were used
   - `gen_ai.usage.output_tokens`: the number of completion tokens that were used
 

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

@@ -457,19 +457,37 @@ To see `generateText` in action, check out [these examples](#examples).
       ],
     },
     {
-      name: 'rawResponse',
-      type: 'RawResponse',
+      name: 'response',
+      type: 'Response',
       optional: true,
-      description: 'Optional raw response data.',
+      description: 'Response metadata.',
       properties: [
         {
-          type: 'RawResponse',
+          type: 'Response',
           parameters: [
+            {
+              name: 'id',
+              type: 'string',
+              description:
+                'The response identifier. The AI SDK uses the ID from the provider response when available, and generates an ID otherwise.',
+            },
+            {
+              name: 'model',
+              type: 'string',
+              description:
+                'The model that was used to generate the response. The AI SDK uses the response model from the provider response when available, and the model from the function call otherwise.',
+            },
+            {
+              name: 'timestamp',
+              type: 'Date',
+              description:
+                'The timestamp of the response. The AI SDK uses the response timestamp from the provider response when available, and creates a timestamp otherwise.',
+            },
             {
               name: 'headers',
               optional: true,
               type: 'Record<string, string>',
-              description: 'Response headers.',
+              description: 'Optional response headers.',
             },
           ],
         },
@@ -552,19 +570,37 @@ To see `generateText` in action, check out [these examples](#examples).
               ],
             },
             {
-              name: 'rawResponse',
-              type: 'RawResponse',
+              name: 'response',
+              type: 'Response',
               optional: true,
-              description: 'Optional raw response data.',
+              description: 'Response metadata.',
               properties: [
                 {
-                  type: 'RawResponse',
+                  type: 'Response',
                   parameters: [
+                    {
+                      name: 'id',
+                      type: 'string',
+                      description:
+                        'The response identifier. The AI SDK uses the ID from the provider response when available, and generates an ID otherwise.',
+                    },
+                    {
+                      name: 'model',
+                      type: 'string',
+                      description:
+                        'The model that was used to generate the response. The AI SDK uses the response model from the provider response when available, and the model from the function call otherwise.',
+                    },
+                    {
+                      name: 'timestamp',
+                      type: 'Date',
+                      description:
+                        'The timestamp of the response. The AI SDK uses the response timestamp from the provider response when available, and creates a timestamp otherwise.',
+                    },
                     {
                       name: 'headers',
                       optional: true,
                       type: 'Record<string, string>',
-                      description: 'Response headers.',
+                      description: 'Optional response headers.',
                     },
                   ],
                 },