From ac21bce96afdc389a22406766300189ea97d8a70 Mon Sep 17 00:00:00 2001 From: Vjeran Grozdanic Date: Mon, 13 Oct 2025 10:57:53 +0200 Subject: [PATCH] fix(ai): Mention that cached and reasoning tokens are subsets of input and output tokens --- .../sdk/telemetry/traces/modules/ai-agents.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx index 113ea6518cae26..c057b1e50a0838 100644 --- a/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx +++ b/develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx @@ -63,13 +63,15 @@ Additional attributes on the span: | Attribute | Type | Requirement Level | Description | Example | | :------------------------------------- | :--- | :---------------- | :------------------------------------------------------------------------ | :------ | | `gen_ai.usage.input_tokens` | int | optional | The number of tokens used in the AI input (prompt). | `10` | -| `gen_ai.usage.input_tokens.cached` | int | optional | The number of cached tokens used in the AI input (prompt) | `50` | +| `gen_ai.usage.input_tokens.cached` | int | optional | The number of cached tokens used in the AI input (prompt) **[2]** | `50` | | `gen_ai.usage.output_tokens` | int | optional | The number of tokens used in the AI response. | `100` | -| `gen_ai.usage.output_tokens.reasoning` | int | optional | The number of tokens used for reasoning. | `30` | +| `gen_ai.usage.output_tokens.reasoning` | int | optional | The number of tokens used for reasoning. **[3]** | `30` | | `gen_ai.usage.total_tokens` | int | optional | The total number of tokens used to process the prompt. (input and output) | `190` | - **[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]:** Each message item uses the format `{role:"", content:""}`. The `role` must be `"user"`, `"assistant"`, `"tool"`, or `"system"`. For messages of the role `tool`, the `content` can be a string or an arbitrary object with information about the tool call. For other messages the `content` can be either a string or a list of dictionaries in the format `{type: "text", text:"..."}`. +- **[2]:** Cached tokens are a subset of input tokens; `gen_ai.usage.input_tokens` includes `gen_ai.usage.input_tokens.cached`. +- **[3]:** Reasoning tokens are a subset of output tokens; `gen_ai.usage.output_tokens` includes `gen_ai.usage.output_tokens.reasoning`. ## AI Client Span @@ -106,13 +108,15 @@ Additional attributes on the span: | Attribute | Type | Requirement Level | Description | Example | | :------------------------------------- | :--- | :---------------- | :------------------------------------------------------------------------ | :------ | | `gen_ai.usage.input_tokens` | int | optional | The number of tokens used in the AI input (prompt). | `10` | -| `gen_ai.usage.input_tokens.cached` | int | optional | The number of cached tokens used in the AI input (prompt) | `50` | +| `gen_ai.usage.input_tokens.cached` | int | optional | The number of cached tokens used in the AI input (prompt) **[2]** | `50` | | `gen_ai.usage.output_tokens` | int | optional | The number of tokens used in the AI response. | `100` | -| `gen_ai.usage.output_tokens.reasoning` | int | optional | The number of tokens used for reasoning. | `30` | +| `gen_ai.usage.output_tokens.reasoning` | int | optional | The number of tokens used for reasoning. **[3]** | `30` | | `gen_ai.usage.total_tokens` | int | optional | The total number of tokens used to process the prompt. (input and output) | `190` | - **[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]:** Each message item uses the format `{role:"", content:""}`. The `role` must be `"user"`, `"assistant"`, `"tool"`, or `"system"`. For messages of the role `tool`, the `content` can be a string or an arbitrary object with information about the tool call. For other messages the `content` can be either a string or a list of dictionaries in the format `{type: "text", text:"..."}`. +- **[2]:** Cached tokens are a subset of input tokens; `gen_ai.usage.input_tokens` includes `gen_ai.usage.input_tokens.cached`. +- **[3]:** Reasoning tokens are a subset of output tokens; `gen_ai.usage.output_tokens` includes `gen_ai.usage.output_tokens.reasoning`. ## Execute Tool Span