From 6c2396fa52bb273a9e60a9c79166209cd1e7934e Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Tue, 27 Oct 2026 11:22:57 +0100 Subject: [PATCH 1/3] chore(ai-sdks): Remove requirement level from attributes --- .../telemetry/traces/modules/ai-agents.mdx | 106 +++++++++--------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx index 016f9a8b117790..5974f905577948 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]**, **[4]**, **[5]**, **[7]** | `'[{"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]**, **[4]**, **[5]**, **[7]** | `'[{"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]:** From 57523ddd0d6f0b20ced4f8aa596bcd74f2b0bec2 Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Tue, 27 Oct 2026 14:13:45 +0100 Subject: [PATCH 2/3] chore(ai-sdks): Document embedding spans --- .../telemetry/traces/modules/ai-agents.mdx | 37 ++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx index 5974f905577948..6001e19099c800 100644 --- a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx +++ b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx @@ -52,7 +52,7 @@ This span represents a request to an AI model or service that generates a respon - Span `op` **SHOULD** be `"gen_ai.{gen_ai.operation.name}"`. (e.g. `"gen_ai.chat"`) - Span `name` **SHOULD** be `"{gen_ai.operation.name} {gen_ai.request.model}"`. (e.g. `"chat o3-mini"`) -- Attribute `gen_ai.operation.name` **MUST** be `"chat"`, `"embeddings"`, `"generate_content"` or `"text_completion"`. +- Attribute `gen_ai.operation.name` **MUST** be `"chat"`, `"generate_content"` or `"text_completion"`. - Attribute `gen_ai.provider.name` **MUST** be the Generative AI product as identified by the client or server instrumentation. (e.g. `"openai"`) - Attribute `gen_ai.request.model` **MUST** be the requested model. (e.g. `"gpt-4o"`) - Attribute `gen_ai.response.model` **MUST** be the concrete response model. (e.g. `"gpt-4o-2024-08-06"`) @@ -111,6 +111,41 @@ Additional attributes on the span: - **[2]:** Cached tokens are a subset of input tokens; `gen_ai.usage.input_tokens` includes `gen_ai.usage.cache_read.input_tokens`. - **[3]:** Reasoning tokens are a subset of output tokens; `gen_ai.usage.output_tokens` includes `gen_ai.usage.reasoning.output_tokens`. +## Embedding Span + +This span represents a request to a provider to encode input into numeric vector embeddings. + +- Span `op` **SHOULD** be `"gen_ai.embeddings"`. +- Span `name` **SHOULD** be `"embeddings {gen_ai.request.model}"`. (e.g. `"embeddings text-embedding-3-small"`) +- Attribute `gen_ai.operation.name` **MUST** be `"embeddings"`. +- Attribute `gen_ai.provider.name` **MUST** be the Generative AI product as identified by the client or server instrumentation. (e.g. `"openai"`) +- Attribute `gen_ai.request.model` **MUST** be the requested model. (e.g. `"text-embedding-3-small"`) +- Attribute `gen_ai.response.model` **MUST** be the concrete response model. (e.g. `"text-embedding-3-small-001"`) +- If the request originates from an agent, the `gen_ai.agent.name` attribute **SHOULD** be set to the name of the agent. (e.g. `"Weather Agent"`) +- If relevant, the `gen_ai.pipeline.name` attribute **SHOULD** be set to the name of the AI workflow, pipeline or chain within which the agent operates. (e.g. `"weather-pipeline"`) + +Additional attributes on the span: + +### Request Data + +| Attribute | Type | Description | Example | +| :-------------------------------- | :----- | :------------------------------------------------ | :--------------------------------------------- | +| `gen_ai.embeddings.input` | string | Input to embed. | `'{"type": "text", "value": "Hello, world!"}'` | +| `gen_ai.request.encoding_formats` | string | The encoding format requested for the embeddings. | `"base64"` | + +### Response Data + +| Attribute | Type | Description | Example | +| :---------------------------------- | :----- | :----------------------------------------- | :------------- | +| `gen_ai.response.id` | string | Unique identifier for the completion. | `"emb_abc123"` | +| `gen_ai.embeddings.dimension.count` | int[] | The dimensions of the returned embeddings. | `[1536]` | + +### Token Usage Data + +| Attribute | Type | Description | Example | +| :-------------------------- | :--- | :-------------------------------------- | :------ | +| `gen_ai.usage.input_tokens` | int | The number of tokens used in the input. | `60` | + ## Execute Tool Span Describes a tool execution. From 2c451e48e5dd5985cb1a5ea6d5919b9da9019cd9 Mon Sep 17 00:00:00 2001 From: Alexander Alderman Webb Date: Tue, 27 Oct 2026 15:49:28 +0100 Subject: [PATCH 3/3] only set what product uses --- .../telemetry/traces/modules/ai-agents.mdx | 23 ++++--------------- 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx index 7eeea59271bdd3..8c36a695731f1c 100644 --- a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx +++ b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx @@ -126,25 +126,10 @@ This span represents a request to a provider to encode input into numeric vector Additional attributes on the span: -### Request Data - -| Attribute | Type | Description | Example | -| :-------------------------------- | :----- | :------------------------------------------------ | :--------------------------------------------- | -| `gen_ai.embeddings.input` | string | Input to embed. | `'{"type": "text", "value": "Hello, world!"}'` | -| `gen_ai.request.encoding_formats` | string | The encoding format requested for the embeddings. | `"base64"` | - -### Response Data - -| Attribute | Type | Description | Example | -| :---------------------------------- | :----- | :----------------------------------------- | :------------- | -| `gen_ai.response.id` | string | Unique identifier for the completion. | `"emb_abc123"` | -| `gen_ai.embeddings.dimension.count` | int[] | The dimensions of the returned embeddings. | `[1536]` | - -### Token Usage Data - -| Attribute | Type | Description | Example | -| :-------------------------- | :--- | :-------------------------------------- | :------ | -| `gen_ai.usage.input_tokens` | int | The number of tokens used in the input. | `60` | +| Attribute | Type | Description | Example | +| :-------------------------- | :----- | :-------------------------------------- | :--------------------------------------------- | +| `gen_ai.embeddings.input` | string | Input to embed. | `'{"type": "text", "value": "Hello, world!"}'` | +| `gen_ai.usage.input_tokens` | int | The number of tokens used in the input. | `60` | ## Execute Tool Span