The cost of tokens used to process the AI input (prompt) in USD (without cached input tokens).
Example123.45
Additional Context
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to calculate total cost, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
Despite the name 'cost.input_tokens', this value is cost in USD, not a token count. For token counts, use gen_ai.usage.input_tokens.
This is the cost of non-cached input tokens only. The cost of cached tokens is excluded from this value.
{
"key": "gen_ai.cost.input_tokens",
"brief": "The cost of tokens used to process the AI input (prompt) in USD (without cached input tokens).",
"type": "double",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": 123.45,
"additional_context": [
"This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to calculate total cost, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.",
"Despite the name 'cost.input_tokens', this value is cost in USD, not a token count. For token counts, use gen_ai.usage.input_tokens.",
"This is the cost of non-cached input tokens only. The cost of cached tokens is excluded from this value."
],
"changelog": [
{
"version": "0.9.0",
"prs": [
397
],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [
228
]
},
{
"version": "0.1.0",
"prs": [
112
]
}
]
}
The cost of tokens used for creating the AI output in USD (without reasoning tokens).
Example123.45
Additional Context
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to calculate total cost, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
Despite the name 'cost.output_tokens', this value is cost in USD, not a token count. For token counts, use gen_ai.usage.output_tokens.
This is the cost of non-reasoning output tokens only. The cost of reasoning tokens is excluded from this value.
{
"key": "gen_ai.cost.output_tokens",
"brief": "The cost of tokens used for creating the AI output in USD (without reasoning tokens).",
"type": "double",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": 123.45,
"additional_context": [
"This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to calculate total cost, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.",
"Despite the name 'cost.output_tokens', this value is cost in USD, not a token count. For token counts, use gen_ai.usage.output_tokens.",
"This is the cost of non-reasoning output tokens only. The cost of reasoning tokens is excluded from this value."
],
"changelog": [
{
"version": "0.9.0",
"prs": [
397
],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [
228
]
},
{
"version": "0.1.0",
"prs": [
112
]
}
]
}
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to calculate total cost, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
Despite the name 'cost.total_tokens', this value is cost in USD, not a token count. For token counts, use gen_ai.usage.total_tokens.
{
"key": "gen_ai.function_id",
"brief": "Framework-specific tracing label for the execution of a function or other unit of execution in a generative AI system.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": "my-awesome-function",
"changelog": [
{
"version": "0.5.0",
"prs": [
308
],
"description": "Added gen_ai.function_id attribute"
}
]
}
The messages passed to the model. It has to be a stringified version of an array of objects. The `role` attribute of each object 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 objects in the format `{type: "text", text:"..."}`.
{
"key": "gen_ai.input.messages",
"brief": "The messages passed to the model. It has to be a stringified version of an array of objects. The `role` attribute of each object 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 objects in the format `{type: \"text\", text:\"...\"}`.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Weather in Paris?\"}]}, {\"role\": \"assistant\", \"parts\": [{\"type\": \"tool_call\", \"id\": \"call_VSPygqKTWdrhaFErNvMV18Yl\", \"name\": \"get_weather\", \"arguments\": {\"location\": \"Paris\"}}]}, {\"role\": \"tool\", \"parts\": [{\"type\": \"tool_call_response\", \"id\": \"call_VSPygqKTWdrhaFErNvMV18Yl\", \"result\": \"rainy, 57°F\"}]}]",
"alias": [
"ai.texts"
],
"changelog": [
{
"version": "0.5.0",
"prs": [
264
]
},
{
"version": "0.4.0",
"prs": [
221
]
}
]
}
The name of the operation being performed. It has the following list of well-known values: 'chat', 'create_agent', 'embeddings', 'execute_tool', 'generate_content', 'invoke_agent', 'text_completion'. If one of them applies, then that value MUST be used. Otherwise a custom value MAY be used.
{
"key": "gen_ai.operation.name",
"brief": "The name of the operation being performed. It has the following list of well-known values: 'chat', 'create_agent', 'embeddings', 'execute_tool', 'generate_content', 'invoke_agent', 'text_completion'. If one of them applies, then that value MUST be used. Otherwise a custom value MAY be used.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": "chat",
"changelog": [
{
"version": "0.4.0",
"prs": [
225
]
},
{
"version": "0.1.0",
"prs": [
62,
127
]
}
]
}
The type of AI operation. Must be one of 'agent' (invoke_agent and create_agent spans), 'ai_client' (any LLM call), 'tool' (execute_tool spans), 'handoff' (handoff spans), 'other' (input and output processors, skill loading, guardrails etc.) . Added during ingestion based on span.op and gen_ai.operation.type. Used to filter and aggregate data in the UI
{
"key": "gen_ai.operation.type",
"brief": "The type of AI operation. Must be one of 'agent' (invoke_agent and create_agent spans), 'ai_client' (any LLM call), 'tool' (execute_tool spans), 'handoff' (handoff spans), 'other' (input and output processors, skill loading, guardrails etc.) . Added during ingestion based on span.op and gen_ai.operation.type. Used to filter and aggregate data in the UI",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": "tool",
"changelog": [
{
"version": "0.4.0",
"prs": [
257
]
},
{
"version": "0.1.0",
"prs": [
113,
127
]
}
]
}
The model's response messages. It has to be a stringified version of an array of message objects, which can include text responses and tool calls.
Example[{"role": "assistant", "parts": [{"type": "text", "content": "The weather in Paris is currently rainy with a temperature of 57°F."}], "finish_reason": "stop"}]
{
"key": "gen_ai.output.messages",
"brief": "The model's response messages. It has to be a stringified version of an array of message objects, which can include text responses and tool calls.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"The weather in Paris is currently rainy with a temperature of 57°F.\"}], \"finish_reason\": \"stop\"}]",
"changelog": [
{
"version": "0.4.0",
"prs": [
221
]
}
]
}
Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation.
{
"key": "gen_ai.request.frequency_penalty",
"brief": "Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation.",
"type": "double",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": 0.5,
"alias": [
"ai.frequency_penalty"
],
"changelog": [
{
"version": "0.4.0",
"prs": [
228
]
},
{
"version": "0.1.0",
"prs": [
57
]
}
]
}
Used to reduce repetitiveness of generated tokens. Similar to frequency_penalty, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies.
{
"key": "gen_ai.request.seed",
"brief": "The seed, ideally models given the same seed and same other parameters will produce the exact same output.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": "1234567890",
"alias": [
"ai.seed"
],
"changelog": [
{
"version": "0.1.0",
"prs": [
57,
127
]
}
]
}
Limits the model to only consider the K most likely next tokens, where K is an integer (e.g., top_k=20 means only the 20 highest probability tokens are considered).
{
"key": "gen_ai.request.top_k",
"brief": "Limits the model to only consider the K most likely next tokens, where K is an integer (e.g., top_k=20 means only the 20 highest probability tokens are considered).",
"type": "integer",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": 35,
"alias": [
"ai.top_k"
],
"changelog": [
{
"version": "0.4.0",
"prs": [
228
]
},
{
"version": "0.1.0",
"prs": [
57
]
}
]
}
Limits the model to only consider tokens whose cumulative probability mass adds up to p, where p is a float between 0 and 1 (e.g., top_p=0.7 means only tokens that sum up to 70% of the probability mass are considered).
{
"key": "gen_ai.request.top_p",
"brief": "Limits the model to only consider tokens whose cumulative probability mass adds up to p, where p is a float between 0 and 1 (e.g., top_p=0.7 means only tokens that sum up to 70% of the probability mass are considered).",
"type": "double",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": 0.7,
"alias": [
"ai.top_p"
],
"changelog": [
{
"version": "0.4.0",
"prs": [
228
]
},
{
"version": "0.1.0",
"prs": [
57
]
}
]
}
{
"key": "gen_ai.tool.call.arguments",
"brief": "The arguments of the tool call. It has to be a stringified version of the arguments to the tool.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": "{\"location\": \"Paris\"}",
"alias": [
"gen_ai.tool.input"
],
"changelog": [
{
"version": "0.5.0",
"prs": [
265
]
},
{
"version": "0.4.0",
"prs": [
221
]
}
]
}
{
"key": "gen_ai.tool.call.result",
"brief": "The result of the tool call. It has to be a stringified version of the result of the tool.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": "rainy, 57°F",
"alias": [
"gen_ai.tool.output",
"gen_ai.tool.message"
],
"changelog": [
{
"version": "0.5.0",
"prs": [
265
]
},
{
"version": "0.4.0",
"prs": [
221
]
}
]
}
The list of source system tool definitions available to the GenAI agent or model.
Example[{"type": "function", "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": {"type": "object", "properties": {"location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}}, "required": ["location", "unit"]}}]
{
"key": "gen_ai.tool.definitions",
"brief": "The list of source system tool definitions available to the GenAI agent or model.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": "[{\"type\": \"function\", \"name\": \"get_current_weather\", \"description\": \"Get the current weather in a given location\", \"parameters\": {\"type\": \"object\", \"properties\": {\"location\": {\"type\": \"string\", \"description\": \"The city and state, e.g. San Francisco, CA\"}, \"unit\": {\"type\": \"string\", \"enum\": [\"celsius\", \"fahrenheit\"]}}, \"required\": [\"location\", \"unit\"]}}]",
"changelog": [
{
"version": "0.4.0",
"prs": [
221
]
}
]
}
{
"key": "gen_ai.tool.description",
"brief": "The description of the tool being used.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": "Searches the web for current information about a topic",
"changelog": [
{
"version": "0.1.0",
"prs": [
62,
127
]
}
]
}
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
{
"key": "gen_ai.usage.cache_creation.input_tokens",
"brief": "The number of tokens written to the cache when processing the AI input (prompt).",
"type": "integer",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": 100,
"alias": [
"gen_ai.usage.input_tokens.cache_write"
],
"additional_context": [
"This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans."
],
"changelog": [
{
"version": "next",
"description": "Added gen_ai.usage.cache_creation.input_tokens attribute"
}
]
}
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
This is a subset of gen_ai.usage.input_tokens, not an independent count. Do not sum this with gen_ai.usage.input_tokens — it is already included.
{
"key": "gen_ai.usage.cache_read.input_tokens",
"brief": "The number of cached tokens used to process the AI input (prompt).",
"type": "integer",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": 50,
"alias": [
"gen_ai.usage.input_tokens.cached"
],
"additional_context": [
"This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.",
"This is a subset of gen_ai.usage.input_tokens, not an independent count. Do not sum this with gen_ai.usage.input_tokens — it is already included."
],
"changelog": [
{
"version": "next",
"description": "Added gen_ai.usage.cache_read.input_tokens attribute"
}
]
}
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
This count includes cached input tokens. gen_ai.usage.cache_read.input_tokens is a subset of this value, not an independent count — do not sum them together.
Changelog
nextUpdate additional_context to reference gen_ai.usage.cache_read.input_tokens
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
This count includes reasoning tokens. gen_ai.usage.reasoning.output_tokens is a subset of this value, not an independent count — do not sum them together.
Changelog
nextUpdate additional_context to reference gen_ai.usage.reasoning.output_tokens
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
This is a subset of gen_ai.usage.output_tokens, not an independent count. Do not sum this with gen_ai.usage.output_tokens — it is already included.
{
"key": "gen_ai.usage.reasoning.output_tokens",
"brief": "The number of tokens used for reasoning to create the AI output.",
"type": "integer",
"pii": {
"key": "maybe"
},
"is_in_otel": true,
"visibility": "public",
"example": 75,
"alias": [
"gen_ai.usage.output_tokens.reasoning"
],
"additional_context": [
"This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.",
"This is a subset of gen_ai.usage.output_tokens, not an independent count. Do not sum this with gen_ai.usage.output_tokens — it is already included."
],
"changelog": [
{
"version": "next",
"description": "Added gen_ai.usage.reasoning.output_tokens attribute"
}
]
}
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
This is the sum of gen_ai.usage.input_tokens and gen_ai.usage.output_tokens. Do not sum this with either of them — they are already included.
{
"key": "gen_ai.usage.total_tokens",
"brief": "The total number of tokens used to process the prompt. (input tokens plus output todkens)",
"type": "integer",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": 20,
"alias": [
"ai.total_tokens.used"
],
"additional_context": [
"This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.",
"This is the sum of gen_ai.usage.input_tokens and gen_ai.usage.output_tokens. Do not sum this with either of them — they are already included."
],
"changelog": [
{
"version": "0.9.0",
"prs": [
397
],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [
228
]
},
{
"version": "0.1.0",
"prs": [
57
]
}
]
}
Deprecated Attributes
These attributes are deprecated and should not be used in new code.
See each attribute for migration guidance.
The available tools for the model. It has to be a stringified version of an array of objects.
Example[{"name": "get_weather", "description": "Get the weather for a given location"}, {"name": "get_news", "description": "Get the news for a given topic"}]
{
"key": "gen_ai.request.available_tools",
"brief": "The available tools for the model. It has to be a stringified version of an array of objects.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": "[{\"name\": \"get_weather\", \"description\": \"Get the weather for a given location\"}, {\"name\": \"get_news\", \"description\": \"Get the news for a given topic\"}]",
"deprecation": {
"replacement": "gen_ai.tool.definitions",
"_status": "normalize"
},
"alias": [],
"changelog": [
{
"version": "0.4.0",
"prs": [
221
]
},
{
"version": "0.1.0",
"prs": [
63,
127
]
}
]
}
The messages passed to the model. It has to be a stringified version of an array of objects. The `role` attribute of each object 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 objects in the format `{type: "text", text:"..."}`.
Example[{"role": "system", "content": "Generate a random number."}, {"role": "user", "content": [{"text": "Generate a random number between 0 and 10.", "type": "text"}]}, {"role": "tool", "content": {"toolCallId": "1", "toolName": "Weather", "output": "rainy"}}]
{
"key": "gen_ai.request.messages",
"brief": "The messages passed to the model. It has to be a stringified version of an array of objects. The `role` attribute of each object 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 objects in the format `{type: \"text\", text:\"...\"}`.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": "[{\"role\": \"system\", \"content\": \"Generate a random number.\"}, {\"role\": \"user\", \"content\": [{\"text\": \"Generate a random number between 0 and 10.\", \"type\": \"text\"}]}, {\"role\": \"tool\", \"content\": {\"toolCallId\": \"1\", \"toolName\": \"Weather\", \"output\": \"rainy\"}}]",
"deprecation": {
"replacement": "gen_ai.input.messages",
"_status": "normalize"
},
"alias": [
"ai.input_messages"
],
"changelog": [
{
"version": "0.4.0",
"prs": [
221
]
},
{
"version": "0.1.0",
"prs": [
63,
74,
108,
119,
122
]
}
]
}
The model's response text messages. It has to be a stringified version of an array of response text messages.
Example["The weather in Paris is rainy and overcast, with temperatures around 57°F", "The weather in London is sunny and warm, with temperatures around 65°F"]
{
"key": "gen_ai.response.text",
"brief": "The model's response text messages. It has to be a stringified version of an array of response text messages.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": "[\"The weather in Paris is rainy and overcast, with temperatures around 57°F\", \"The weather in London is sunny and warm, with temperatures around 65°F\"]",
"deprecation": {
"replacement": "gen_ai.output.messages",
"_status": "normalize"
},
"alias": [],
"changelog": [
{
"version": "0.4.0",
"prs": [
221
]
},
{
"version": "0.1.0",
"prs": [
63,
74
]
}
]
}
{
"key": "gen_ai.tool.input",
"brief": "The input of the tool being used. It has to be a stringified version of the input to the tool.",
"type": "string",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": "{\"location\": \"Paris\"}",
"deprecation": {
"replacement": "gen_ai.tool.call.arguments",
"_status": "normalize"
},
"alias": [
"gen_ai.tool.call.arguments"
],
"changelog": [
{
"version": "0.5.0",
"prs": [
265
]
},
{
"version": "0.1.0",
"prs": [
63,
74
]
}
]
}
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
Changelog
nextDeprecate in favor of gen_ai.usage.cache_creation.input_tokens
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
This is a subset of gen_ai.usage.input_tokens, not an independent count. Do not sum this with gen_ai.usage.input_tokens — it is already included.
Changelog
nextDeprecate in favor of gen_ai.usage.cache_read.input_tokens
{
"key": "gen_ai.usage.input_tokens.cached",
"brief": "The number of cached tokens used to process the AI input (prompt).",
"type": "integer",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": 50,
"deprecation": {
"replacement": "gen_ai.usage.cache_read.input_tokens",
"_status": "backfill"
},
"alias": [
"gen_ai.usage.cache_read.input_tokens"
],
"additional_context": [
"This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.",
"This is a subset of gen_ai.usage.input_tokens, not an independent count. Do not sum this with gen_ai.usage.input_tokens — it is already included."
],
"changelog": [
{
"version": "next",
"description": "Deprecate in favor of gen_ai.usage.cache_read.input_tokens"
},
{
"version": "0.9.0",
"prs": [
397
],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [
228
]
},
{
"version": "0.1.0",
"prs": [
62,
112
]
}
]
}
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.
This is a subset of gen_ai.usage.output_tokens, not an independent count. Do not sum this with gen_ai.usage.output_tokens — it is already included.
Changelog
nextDeprecate in favor of gen_ai.usage.reasoning.output_tokens
{
"key": "gen_ai.usage.output_tokens.reasoning",
"brief": "The number of tokens used for reasoning to create the AI output.",
"type": "integer",
"pii": {
"key": "maybe"
},
"is_in_otel": false,
"visibility": "public",
"example": 75,
"deprecation": {
"replacement": "gen_ai.usage.reasoning.output_tokens",
"_status": "backfill"
},
"alias": [
"gen_ai.usage.reasoning.output_tokens"
],
"additional_context": [
"This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.",
"This is a subset of gen_ai.usage.output_tokens, not an independent count. Do not sum this with gen_ai.usage.output_tokens — it is already included."
],
"changelog": [
{
"version": "next",
"description": "Deprecate in favor of gen_ai.usage.reasoning.output_tokens"
},
{
"version": "0.9.0",
"prs": [
397
],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [
228
]
},
{
"version": "0.1.0",
"prs": [
62,
112
]
}
]
}
This attribute appears on both agent parent spans (aggregated totals) and LLM child spans (per-call values). When using sum() to count tokens, filter to gen_ai.operation.type:ai_client to avoid double-counting hierarchical spans.