Skip to content

feat(attributes): Add additional_context to gen_ai cost and usage attributes #397

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
matejminar merged 1 commit into from
May 21, 2026
Merged

feat(attributes): Add additional_context to gen_ai cost and usage attributes #397

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 67 additions & 3 deletions javascript/sentry-conventions/src/attributes.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17430,9 +17430,15 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
visibility: 'public',
example: 123.45,
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [112] },
],
additionalContext: [
'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.',
],
},
[GEN_AI_COST_OUTPUT_TOKENS]: {
brief: 'The cost of tokens used for creating the AI output in USD (without reasoning tokens).',
Expand All @@ -17444,9 +17450,15 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
visibility: 'public',
example: 123.45,
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [112] },
],
additionalContext: [
'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.',
],
},
[GEN_AI_COST_TOTAL_TOKENS]: {
brief: 'The total cost for the tokens used.',
Expand All @@ -17459,10 +17471,15 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
example: 12.34,
aliases: [AI_TOTAL_COST],
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.5.0', prs: [264] },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [126] },
],
additionalContext: [
'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.",
],
},
[GEN_AI_EMBEDDINGS_INPUT]: {
brief: 'The input to the embeddings model.',
Expand Down Expand Up @@ -18045,7 +18062,15 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
replacement: 'gen_ai.usage.output_tokens',
},
aliases: [AI_COMPLETION_TOKENS_USED, GEN_AI_USAGE_OUTPUT_TOKENS],
changelog: [{ version: '0.4.0', prs: [228] }, { version: '0.1.0', prs: [61] }, { version: '0.0.0' }],
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [61] },
{ version: '0.0.0' },
],
additionalContext: [
'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.',
],
},
[GEN_AI_USAGE_INPUT_TOKENS]: {
brief: 'The number of tokens used to process the AI input (prompt) including cached input tokens.',
Expand All @@ -18058,11 +18083,16 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
example: 10,
aliases: [AI_PROMPT_TOKENS_USED, GEN_AI_USAGE_PROMPT_TOKENS],
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.5.0', prs: [261] },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [112] },
{ version: '0.0.0' },
],
additionalContext: [
'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.input_tokens.cached is a subset of this value, not an independent count — do not sum them together.',
],
},
[GEN_AI_USAGE_INPUT_TOKENS_CACHED]: {
brief: 'The number of cached tokens used to process the AI input (prompt).',
Expand All @@ -18074,9 +18104,14 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
visibility: 'public',
example: 50,
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [62, 112] },
],
additionalContext: [
'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.',
],
},
[GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE]: {
brief: 'The number of tokens written to the cache when processing the AI input (prompt).',
Expand All @@ -18087,7 +18122,13 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
isInOtel: false,
visibility: 'public',
example: 100,
changelog: [{ version: '0.4.0', prs: [217, 228] }],
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.4.0', prs: [217, 228] },
],
additionalContext: [
'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.',
],
},
[GEN_AI_USAGE_OUTPUT_TOKENS]: {
brief: 'The number of tokens used for creating the AI output (including reasoning tokens).',
Expand All @@ -18100,11 +18141,16 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
example: 10,
aliases: [AI_COMPLETION_TOKENS_USED, GEN_AI_USAGE_COMPLETION_TOKENS],
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.5.0', prs: [261] },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [112] },
{ version: '0.0.0' },
],
additionalContext: [
'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.output_tokens.reasoning is a subset of this value, not an independent count — do not sum them together.',
],
},
[GEN_AI_USAGE_OUTPUT_TOKENS_REASONING]: {
brief: 'The number of tokens used for reasoning to create the AI output.',
Expand All @@ -18116,9 +18162,14 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
visibility: 'public',
example: 75,
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [62, 112] },
],
additionalContext: [
'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.',
],
},
[GEN_AI_USAGE_PROMPT_TOKENS]: {
brief: 'The number of tokens used in the GenAI input (prompt).',
Expand All @@ -18133,7 +18184,15 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
replacement: 'gen_ai.usage.input_tokens',
},
aliases: [AI_PROMPT_TOKENS_USED, GEN_AI_USAGE_INPUT_TOKENS],
changelog: [{ version: '0.4.0', prs: [228] }, { version: '0.1.0', prs: [61] }, { version: '0.0.0' }],
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [61] },
{ version: '0.0.0' },
],
additionalContext: [
'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.',
],
},
[GEN_AI_USAGE_TOTAL_TOKENS]: {
brief: 'The total number of tokens used to process the prompt. (input tokens plus output todkens)',
Expand All @@ -18146,9 +18205,14 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
example: 20,
aliases: [AI_TOTAL_TOKENS_USED],
changelog: [
{ version: 'next', prs: [397], description: 'Add additional_context' },
{ version: '0.4.0', prs: [228] },
{ version: '0.1.0', prs: [57] },
],
additionalContext: [
'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.',
],
},
[GRAPHQL_DOCUMENT]: {
brief: 'The GraphQL document being executed.',
Expand Down
10 changes: 10 additions & 0 deletions model/attributes/gen_ai/gen_ai__cost__input_tokens.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,17 @@
"is_in_otel": false,
"example": 123.45,
"visibility": "public",
"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": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [228]
Expand Down
10 changes: 10 additions & 0 deletions model/attributes/gen_ai/gen_ai__cost__output_tokens.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,17 @@
"is_in_otel": false,
"example": 123.45,
"visibility": "public",
"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": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [228]
Expand Down
9 changes: 9 additions & 0 deletions model/attributes/gen_ai/gen_ai__cost__total_tokens.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,18 @@
},
"is_in_otel": false,
"example": 12.34,
"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.total_tokens', this value is cost in USD, not a token count. For token counts, use gen_ai.usage.total_tokens."
],
"alias": ["ai.total_cost"],
"visibility": "public",
"changelog": [
{
"version": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.5.0",
"prs": [264]
Expand Down
8 changes: 8 additions & 0 deletions model/attributes/gen_ai/gen_ai__usage__completion_tokens.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,20 @@
"is_in_otel": true,
"example": 10,
"alias": ["ai.completion_tokens.used", "gen_ai.usage.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."
],
"deprecation": {
"_status": "backfill",
"replacement": "gen_ai.usage.output_tokens"
},
"visibility": "public",
"changelog": [
{
"version": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [228]
Expand Down
9 changes: 9 additions & 0 deletions model/attributes/gen_ai/gen_ai__usage__input_tokens.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,18 @@
},
"is_in_otel": true,
"example": 10,
"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 count includes cached input tokens. gen_ai.usage.input_tokens.cached is a subset of this value, not an independent count \u2014 do not sum them together."
],
"alias": ["ai.prompt_tokens.used", "gen_ai.usage.prompt_tokens"],
"visibility": "public",
"changelog": [
{
"version": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.5.0",
"prs": [261]
Expand Down
8 changes: 8 additions & 0 deletions model/attributes/gen_ai/gen_ai__usage__input_tokens__cache_write.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,15 @@
"is_in_otel": false,
"example": 100,
"visibility": "public",
"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",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [217, 228]
Expand Down
9 changes: 9 additions & 0 deletions model/attributes/gen_ai/gen_ai__usage__input_tokens__cached.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,16 @@
"is_in_otel": false,
"example": 50,
"visibility": "public",
"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 \u2014 it is already included."
],
"changelog": [
{
"version": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [228]
Expand Down
9 changes: 9 additions & 0 deletions model/attributes/gen_ai/gen_ai__usage__output_tokens.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,18 @@
},
"is_in_otel": true,
"example": 10,
"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 count includes reasoning tokens. gen_ai.usage.output_tokens.reasoning is a subset of this value, not an independent count \u2014 do not sum them together."
],
"alias": ["ai.completion_tokens.used", "gen_ai.usage.completion_tokens"],
"visibility": "public",
"changelog": [
{
"version": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.5.0",
"prs": [261]
Expand Down
9 changes: 9 additions & 0 deletions model/attributes/gen_ai/gen_ai__usage__output_tokens__reasoning.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,16 @@
"is_in_otel": false,
"example": 75,
"visibility": "public",
"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 \u2014 it is already included."
],
"changelog": [
{
"version": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [228]
Expand Down
8 changes: 8 additions & 0 deletions model/attributes/gen_ai/gen_ai__usage__prompt_tokens.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,20 @@
"is_in_otel": true,
"example": 20,
"alias": ["ai.prompt_tokens.used", "gen_ai.usage.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."
],
"deprecation": {
"_status": "backfill",
"replacement": "gen_ai.usage.input_tokens"
},
"visibility": "public",
"changelog": [
{
"version": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [228]
Expand Down
9 changes: 9 additions & 0 deletions model/attributes/gen_ai/gen_ai__usage__total_tokens.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,18 @@
},
"is_in_otel": false,
"example": 20,
"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 \u2014 they are already included."
],
"alias": ["ai.total_tokens.used"],
"visibility": "public",
"changelog": [
{
"version": "next",
"prs": [397],
"description": "Add additional_context"
},
{
"version": "0.4.0",
"prs": [228]
Expand Down
Loading
Loading