diff --git a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx index 5b4c67b164db88..3e2d4718ad7873 100644 --- a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx +++ b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx @@ -32,16 +32,16 @@ Additional attributes on the span: ### Request Data -| Attribute | Type | Requirement Level | Description | Example | -| :--------------------------------- | :----- | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- | -| `gen_ai.input.messages` | string | optional | List of dictionaries describing the messages (prompts) given to the agent. **[0]**, **[1]** | `'[{"role": "user", "parts": [{"type": "text", "content": "..."}]}]'` | -| `gen_ai.system_instructions` | string | optional | The system instructions passed to the model. | `"You are a helpful assistant."` | +| Attribute | Type | Description | Example | +| :--------------------------- | :----- | :--------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- | +| `gen_ai.input.messages` | string | List of dictionaries describing the messages (prompts) given to the agent. **[0]**, **[1]**, **[4]**, **[5]**, **[7]** | `'[{"role": "user", "parts": [{"type": "text", "content": "..."}]}]'` | +| `gen_ai.system_instructions` | string | The system instructions passed to the model. | `"You are a helpful assistant."` | ### Response Data -| Attribute | Type | Requirement Level | Description | Example | -| :--------------------------- | :------ | :---------------- | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | -| `gen_ai.output.messages` | string | optional | Stringified array of message objects representing the model's output. **[0]**, **[1]** | `'[{"role": "assistant", "parts": [{"type": "text", "content": "..."}]}]'` | +| Attribute | Type | Description | Example | +| :----------------------- | :----- | :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | +| `gen_ai.output.messages` | string | Stringified array of message objects representing the model's output. **[0]**, **[1]** | `'[{"role": "assistant", "parts": [{"type": "text", "content": "..."}]}]'` | - **[0]:** Span attributes only allow primitive data types (like `int`, `float`, `boolean`, `string`). This means you need to use a stringified version of a list of dictionaries. Do NOT set the object/array `[{"foo": "bar"}]` but rather the string `'[{"foo": "bar"}]'` (must be parsable JSON). - **[1]:** Messages use the format `{role, parts}` where `parts` is an array of typed objects: `[{"role": "user", "parts": [{"type": "text", "content": "..."}]}]`. The `role` must be `"user"`, `"assistant"`, `"tool"`, or `"system"`. Each part has a `type`; common types include `"text"` (user-visible content), `"reasoning"` (internal thinking/chain-of-thought), `"tool_call"`, and `"tool_call_response"`. Use `{"type": "reasoning", "content": "..."}` for the model's thinking output — Sentry surfaces it separately and does not render it as a user-visible message in Conversations, so do not represent thinking content as a `"text"` part. For backwards compatibility, the legacy format `{role, content}` is also accepted. @@ -63,48 +63,48 @@ Additional attributes on the span: ### Request Data -| Attribute | Type | Requirement Level | Description | Example | -| :--------------------------------- | :----- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- | -| `gen_ai.input.messages` | string | optional | List of dictionaries describing the messages (prompts) sent to the LLM. **[0]**, **[1]** | `'[{"role": "user", "parts": [{"type": "text", "content": "..."}]}]'` | -| `gen_ai.tool.definitions` | string | optional | List of dictionaries describing the available tools. **[0]** | `'[{"name": "random_number", "description": "..."}, ...]'` | -| `gen_ai.system_instructions` | string | optional | The system instructions passed to the model. | `"You are a helpful assistant."` | -| `gen_ai.request.max_tokens` | int | optional | Model configuration parameter. | `500` | -| `gen_ai.request.seed` | string | optional | Seed for reproducible outputs. | `"12345"` | -| `gen_ai.request.frequency_penalty` | float | optional | Model configuration parameter. | `0.5` | -| `gen_ai.request.presence_penalty` | float | optional | Model configuration parameter. | `0.5` | -| `gen_ai.request.temperature` | float | optional | Model configuration parameter. | `0.1` | -| `gen_ai.request.top_p` | float | optional | Model configuration parameter. | `0.7` | -| `gen_ai.request.top_k` | int | optional | Limits model to K most likely next tokens. | `40` | -| `gen_ai.request.reasoning.level` | string | optional | The reasoning or thinking effort level requested for a GenAI model. Supported values vary by provider. | `"medium"` | -| `gen_ai.request.messages` | string | optional | **Deprecated.** Use `gen_ai.input.messages` instead. List of dictionaries describing the messages (prompts) sent to the LLM. **[0]** | `'[{"role": "system", "content": "..."}, ...]'` | -| `gen_ai.request.available_tools` | string | optional | **Deprecated.** Use `gen_ai.tool.definitions` instead. List of dictionaries describing the available tools. **[0]** | `'[{"name": "random_number", "description": "..."}, ...]'` | +| Attribute | Type | Description | Example | +| :--------------------------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------- | +| `gen_ai.input.messages` | string | List of dictionaries describing the messages (prompts) sent to the LLM. **[0]**, **[1]**, **[4]**, **[5]**, **[7]** | `'[{"role": "user", "parts": [{"type": "text", "content": "..."}]}]'` | +| `gen_ai.tool.definitions` | string | List of dictionaries describing the available tools. **[0]** | `'[{"name": "random_number", "description": "..."}, ...]'` | +| `gen_ai.system_instructions` | string | The system instructions passed to the model. | `"You are a helpful assistant."` | +| `gen_ai.request.max_tokens` | int | Model configuration parameter. | `500` | +| `gen_ai.request.seed` | string | Seed for reproducible outputs. | `"12345"` | +| `gen_ai.request.frequency_penalty` | float | Model configuration parameter. | `0.5` | +| `gen_ai.request.presence_penalty` | float | Model configuration parameter. | `0.5` | +| `gen_ai.request.temperature` | float | Model configuration parameter. | `0.1` | +| `gen_ai.request.top_p` | float | Model configuration parameter. | `0.7` | +| `gen_ai.request.top_k` | int | Limits model to K most likely next tokens. | `40` | +| `gen_ai.request.reasoning.level` | string | The reasoning or thinking effort level requested for a GenAI model. Supported values vary by provider. | `"medium"` | +| `gen_ai.request.messages` | string | **Deprecated.** Use `gen_ai.input.messages` instead. List of dictionaries describing the messages (prompts) sent to the LLM. **[0]** | `'[{"role": "system", "content": "..."}, ...]'` | +| `gen_ai.request.available_tools` | string | **Deprecated.** Use `gen_ai.tool.definitions` instead. List of dictionaries describing the available tools. **[0]** | `'[{"name": "random_number", "description": "..."}, ...]'` | ### Response Data -| Attribute | Type | Requirement Level | Description | Example | -| :------------------------------------ | :------ | :---------------- | :------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------- | -| `gen_ai.output.messages` | string | optional | Stringified array of message objects representing the model's output. **[0]**, **[1]** | `'[{"role": "assistant", "parts": [{"type": "text", "content": "..."}]}]'` | -| `gen_ai.response.finish_reasons` | string | optional | The reason why the model stopped generating. | `"stop"` | -| `gen_ai.response.id` | string | optional | Unique identifier for the completion. | `"chatcmpl-abc123"` | -| `gen_ai.response.streaming` | boolean | optional | Whether response was streamed asynchronously. | `true` | -| `gen_ai.response.time_to_first_chunk` | double | optional | Seconds until first response chunk in streaming. | `0.5` | -| `gen_ai.response.text` | string | optional | **Deprecated.** Use `gen_ai.output.messages` instead. The text representation of the model's response. **[0]** | `"The weather in Paris is rainy"` | -| `gen_ai.response.tool_calls` | string | optional | **Deprecated.** Use `gen_ai.output.messages` instead. The tool calls in the model's response. **[0]** | `'[{"name": "random_number", "type": "function_call", "arguments": "..."}]'` | -| `gen_ai.response.time_to_first_token` | double | optional | **Deprecated.** Use `gen_ai.response.time_to_first_chunk` instead. Seconds until first response chunk in streaming. | `0.5` | +| Attribute | Type | Description | Example | +| :------------------------------------ | :------ | :------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------- | +| `gen_ai.output.messages` | string | Stringified array of message objects representing the model's output. **[0]**, **[1]** | `'[{"role": "assistant", "parts": [{"type": "text", "content": "..."}]}]'` | +| `gen_ai.response.finish_reasons` | string | The reason why the model stopped generating. | `"stop"` | +| `gen_ai.response.id` | string | Unique identifier for the completion. | `"chatcmpl-abc123"` | +| `gen_ai.response.streaming` | boolean | Whether response was streamed asynchronously. | `true` | +| `gen_ai.response.time_to_first_chunk` | double | Seconds until first response chunk in streaming. | `0.5` | +| `gen_ai.response.text` | string | **Deprecated.** Use `gen_ai.output.messages` instead. The text representation of the model's response. **[0]** | `"The weather in Paris is rainy"` | +| `gen_ai.response.tool_calls` | string | **Deprecated.** Use `gen_ai.output.messages` instead. The tool calls in the model's response. **[0]** | `'[{"name": "random_number", "type": "function_call", "arguments": "..."}]'` | +| `gen_ai.response.time_to_first_token` | double | **Deprecated.** Use `gen_ai.response.time_to_first_chunk` instead. Seconds until first response chunk in streaming. | `0.5` | ### Token Usage Data -| Attribute | Type | Requirement Level | Description | Example | -| :----------------------------------------- | :--- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------- | :------ | -| `gen_ai.usage.input_tokens` | int | optional | The number of tokens used in the AI input (prompt), including cached tokens. **[2]** | `60` | -| `gen_ai.usage.cache_read.input_tokens` | int | optional | The number of cached tokens used in the AI input (prompt). | `50` | -| `gen_ai.usage.cache_creation.input_tokens` | int | optional | Tokens written to cache when processing input. | `20` | -| `gen_ai.usage.output_tokens` | int | optional | The number of tokens used in the AI output, including reasoning tokens. **[3]** | `130` | -| `gen_ai.usage.reasoning.output_tokens` | int | optional | The number of tokens used for reasoning. | `30` | -| `gen_ai.usage.total_tokens` | int | optional | The sum of `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. | `190` | -| `gen_ai.usage.input_tokens.cached` | int | optional | **Deprecated.** Use `gen_ai.usage.cache_read.input_tokens` instead. The number of cached tokens used in the AI input (prompt). | `50` | -| `gen_ai.usage.input_tokens.cache_write` | int | optional | **Deprecated.** Use `gen_ai.usage.cache_creation.input_tokens` instead. Tokens written to cache when processing input. | `20` | -| `gen_ai.usage.output_tokens.reasoning` | int | optional | **Deprecated.** Use `gen_ai.usage.reasoning.output_tokens` instead. The number of tokens used for reasoning. | `30` | +| Attribute | Type | Description | Example | +| :----------------------------------------- | :--- | :----------------------------------------------------------------------------------------------------------------------------- | :------ | +| `gen_ai.usage.input_tokens` | int | The number of tokens used in the AI input (prompt), including cached tokens. **[2]** | `60` | +| `gen_ai.usage.cache_read.input_tokens` | int | The number of cached tokens used in the AI input (prompt). | `50` | +| `gen_ai.usage.cache_creation.input_tokens` | int | Tokens written to cache when processing input. | `20` | +| `gen_ai.usage.output_tokens` | int | The number of tokens used in the AI output, including reasoning tokens. **[3]** | `130` | +| `gen_ai.usage.reasoning.output_tokens` | int | The number of tokens used for reasoning. | `30` | +| `gen_ai.usage.total_tokens` | int | The sum of `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. | `190` | +| `gen_ai.usage.input_tokens.cached` | int | **Deprecated.** Use `gen_ai.usage.cache_read.input_tokens` instead. The number of cached tokens used in the AI input (prompt). | `50` | +| `gen_ai.usage.input_tokens.cache_write` | int | **Deprecated.** Use `gen_ai.usage.cache_creation.input_tokens` instead. Tokens written to cache when processing input. | `20` | +| `gen_ai.usage.output_tokens.reasoning` | int | **Deprecated.** Use `gen_ai.usage.reasoning.output_tokens` instead. The number of tokens used for reasoning. | `30` | - **[0]:** Span attributes only allow primitive data types (like `int`, `float`, `boolean`, `string`). This means you need to use a stringified version of a list of dictionaries. Do NOT set the object/array `[{"foo": "bar"}]` but rather the string `'[{"foo": "bar"}]'` (must be parsable JSON). - **[1]:** Messages use the format `{role, parts}` where `parts` is an array of typed objects: `[{"role": "user", "parts": [{"type": "text", "content": "..."}]}]`. The `role` must be `"user"`, `"assistant"`, `"tool"`, or `"system"`. Each part has a `type`; common types include `"text"` (user-visible content), `"reasoning"` (internal thinking/chain-of-thought), `"tool_call"`, and `"tool_call_response"`. Use `{"type": "reasoning", "content": "..."}` for the model's thinking output — Sentry surfaces it separately and does not render it as a user-visible message in Conversations, so do not represent thinking content as a `"text"` part. For backwards compatibility, the legacy format `{role, content}` is also accepted. @@ -126,16 +126,16 @@ Additional attributes on the span: ### Tool Data -| Attribute | Type | Requirement Level | Description | Example | -| :--------------------------- | :----- | :---------------- | :------------------------------------------------------------------------------------------------------------- | :----------------------------------------- | -| `gen_ai.tool.name` | string | optional | Name of the tool executed. | `"random_number"` | -| `gen_ai.tool.description` | string | optional | Description of the tool executed. | `"Tool returning a random number"` | -| `gen_ai.tool.type` | string | optional | The type of the tools. | `"function"`; `"extension"`; `"datastore"` | -| `gen_ai.tool.call.arguments` | string | optional | Arguments of the tool call (stringified). | `'{"max":10}'` | -| `gen_ai.tool.call.result` | string | optional | Result of the tool call (stringified). | `"7"` | -| `gen_ai.tool.message` | string | optional | Response from a tool/function call passed to model. | `"The random number is 7"` | -| `gen_ai.tool.input` | string | optional | **Deprecated.** Use `gen_ai.tool.call.arguments` instead. Input that was given to the executed tool as string. | `'{"max":10}'` | -| `gen_ai.tool.output` | string | optional | **Deprecated.** Use `gen_ai.tool.call.result` instead. The output from the tool. | `"7"` | +| Attribute | Type | Description | Example | +| :--------------------------- | :----- | :------------------------------------------------------------------------------------------------------------- | :----------------------------------------- | +| `gen_ai.tool.name` | string | Name of the tool executed. | `"random_number"` | +| `gen_ai.tool.description` | string | Description of the tool executed. | `"Tool returning a random number"` | +| `gen_ai.tool.type` | string | The type of the tools. | `"function"`; `"extension"`; `"datastore"` | +| `gen_ai.tool.call.arguments` | string | Arguments of the tool call (stringified). | `'{"max":10}'` | +| `gen_ai.tool.call.result` | string | Result of the tool call (stringified). | `"7"` | +| `gen_ai.tool.message` | string | Response from a tool/function call passed to model. | `"The random number is 7"` | +| `gen_ai.tool.input` | string | **Deprecated.** Use `gen_ai.tool.call.arguments` instead. Input that was given to the executed tool as string. | `'{"max":10}'` | +| `gen_ai.tool.output` | string | **Deprecated.** Use `gen_ai.tool.call.result` instead. The output from the tool. | `"7"` | **[2]:**