Skip to content

feat(attributes): Add legacy gen_ai cache token attributes (deprecated) #582

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
vgrozdanic merged 1 commit into from
Sep 14, 2026
Merged

feat(attributes): Add legacy gen_ai cache token attributes (deprecated) #582

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
150 changes: 137 additions & 13 deletions javascript/sentry-conventions/src/attributes.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8705,7 +8705,7 @@ export type GEN_AI_TOOL_TYPE_TYPE = string;
* Attribute defined in OTEL: Yes
* Visibility: public
*
* Aliases: {@link GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE} `gen_ai.usage.input_tokens.cache_write`
* Aliases: {@link GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE} `gen_ai.usage.input_tokens.cache_write`, {@link _GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS} `gen_ai.usage.cache_creation_input_tokens`
*
* @example 100
*/
Expand All @@ -8716,6 +8716,30 @@ export const GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = 'gen_ai.usage.cache_crea
*/
export type GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS_TYPE = number;

// Path: model/attributes/gen_ai/gen_ai__usage__cache_creation_input_tokens.json

/**
* The number of tokens written to the cache when processing the AI input (prompt). `gen_ai.usage.cache_creation_input_tokens`
*
* Attribute Value Type: `number` {@link _GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS_TYPE}
*
* Apply Scrubbing: manual
*
* Attribute defined in OTEL: No
* Visibility: public
*
* Aliases: {@link GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS} `gen_ai.usage.cache_creation.input_tokens`, {@link GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE} `gen_ai.usage.input_tokens.cache_write`
*
* @deprecated Use {@link GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS} (gen_ai.usage.cache_creation.input_tokens) instead - This attribute is being deprecated in favor of gen_ai.usage.cache_creation.input_tokens.
* @example 100
*/
export const _GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS = 'gen_ai.usage.cache_creation_input_tokens';

/**
* Type for {@link _GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS} gen_ai.usage.cache_creation_input_tokens
*/
export type _GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS_TYPE = number;

// Path: model/attributes/gen_ai/gen_ai__usage__cache_read__input_tokens.json

/**
Expand All @@ -8728,7 +8752,7 @@ export type GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS_TYPE = number;
* Attribute defined in OTEL: Yes
* Visibility: public
*
* Aliases: {@link GEN_AI_USAGE_INPUT_TOKENS_CACHED} `gen_ai.usage.input_tokens.cached`
* Aliases: {@link GEN_AI_USAGE_INPUT_TOKENS_CACHED} `gen_ai.usage.input_tokens.cached`, {@link _GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS} `gen_ai.usage.cache_read_input_tokens`
*
* @example 50
*/
Expand All @@ -8739,6 +8763,30 @@ export const GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = 'gen_ai.usage.cache_read.inp
*/
export type GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS_TYPE = number;

// Path: model/attributes/gen_ai/gen_ai__usage__cache_read_input_tokens.json

/**
* The number of cached tokens used to process the AI input (prompt). `gen_ai.usage.cache_read_input_tokens`
*
* Attribute Value Type: `number` {@link _GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS_TYPE}
*
* Apply Scrubbing: manual
*
* Attribute defined in OTEL: No
* Visibility: public
*
* Aliases: {@link GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS} `gen_ai.usage.cache_read.input_tokens`, {@link GEN_AI_USAGE_INPUT_TOKENS_CACHED} `gen_ai.usage.input_tokens.cached`
*
* @deprecated Use {@link GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS} (gen_ai.usage.cache_read.input_tokens) instead - This attribute is being deprecated in favor of gen_ai.usage.cache_read.input_tokens.
* @example 50
*/
export const _GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS = 'gen_ai.usage.cache_read_input_tokens';

/**
* Type for {@link _GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS} gen_ai.usage.cache_read_input_tokens
*/
export type _GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS_TYPE = number;

// Path: model/attributes/gen_ai/gen_ai__usage__completion_tokens.json

/**
Expand Down Expand Up @@ -8798,7 +8846,7 @@ export type GEN_AI_USAGE_INPUT_TOKENS_TYPE = number;
* Attribute defined in OTEL: No
* Visibility: public
*
* Aliases: {@link GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS} `gen_ai.usage.cache_read.input_tokens`
* Aliases: {@link GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS} `gen_ai.usage.cache_read.input_tokens`, {@link _GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS} `gen_ai.usage.cache_read_input_tokens`
*
* @deprecated Use {@link GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS} (gen_ai.usage.cache_read.input_tokens) instead
* @example 50
Expand All @@ -8822,7 +8870,7 @@ export type GEN_AI_USAGE_INPUT_TOKENS_CACHED_TYPE = number;
* Attribute defined in OTEL: No
* Visibility: public
*
* Aliases: {@link GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS} `gen_ai.usage.cache_creation.input_tokens`
* Aliases: {@link GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS} `gen_ai.usage.cache_creation.input_tokens`, {@link _GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS} `gen_ai.usage.cache_creation_input_tokens`
*
* @deprecated Use {@link GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS} (gen_ai.usage.cache_creation.input_tokens) instead
* @example 100
Expand Down Expand Up @@ -19145,7 +19193,9 @@ export const ATTRIBUTE_TYPE: Record<string, AttributeType> = {
'gen_ai.tool.output': 'string',
'gen_ai.tool.type': 'string',
'gen_ai.usage.cache_creation.input_tokens': 'integer',
'gen_ai.usage.cache_creation_input_tokens': 'integer',
'gen_ai.usage.cache_read.input_tokens': 'integer',
'gen_ai.usage.cache_read_input_tokens': 'integer',
'gen_ai.usage.completion_tokens': 'integer',
'gen_ai.usage.input_tokens': 'integer',
'gen_ai.usage.input_tokens.cached': 'integer',
Expand Down Expand Up @@ -19984,7 +20034,9 @@ export type AttributeName =
| typeof GEN_AI_TOOL_OUTPUT
| typeof GEN_AI_TOOL_TYPE
| typeof GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS
| typeof _GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS
| typeof GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS
| typeof _GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS
| typeof GEN_AI_USAGE_COMPLETION_TOKENS
| typeof GEN_AI_USAGE_INPUT_TOKENS
| typeof GEN_AI_USAGE_INPUT_TOKENS_CACHED
Expand Down Expand Up @@ -26531,38 +26583,98 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
'gen_ai.usage.cache_creation.input_tokens': {
brief: 'The number of tokens written to the cache when processing the AI input (prompt).',
type: 'integer',
keys: ['gen_ai.usage.cache_creation.input_tokens', 'gen_ai.usage.input_tokens.cache_write'],
keys: [
'gen_ai.usage.cache_creation.input_tokens',
'gen_ai.usage.cache_creation_input_tokens',
'gen_ai.usage.input_tokens.cache_write',
],
applyScrubbing: {
key: 'manual',
},
isInOtel: true,
visibility: 'public',
example: 100,
aliases: ['gen_ai.usage.input_tokens.cache_write'],
aliases: ['gen_ai.usage.input_tokens.cache_write', 'gen_ai.usage.cache_creation_input_tokens'],
changelog: [
{ version: 'next', description: 'Added gen_ai.usage.cache_creation_input_tokens as an alias' },
{ version: '0.11.0', prs: [418], description: 'Added gen_ai.usage.cache_creation.input_tokens attribute' },
],
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.cache_creation_input_tokens': {
brief: 'The number of tokens written to the cache when processing the AI input (prompt).',
type: 'integer',
keys: [
'gen_ai.usage.cache_creation.input_tokens',
'gen_ai.usage.cache_creation_input_tokens',
'gen_ai.usage.input_tokens.cache_write',
],
applyScrubbing: {
key: 'manual',
},
isInOtel: false,
visibility: 'public',
example: 100,
examples: [100],
deprecation: {
replacement: 'gen_ai.usage.cache_creation.input_tokens',
reason: 'This attribute is being deprecated in favor of gen_ai.usage.cache_creation.input_tokens.',
status: 'backfill',
},
aliases: ['gen_ai.usage.cache_creation.input_tokens', 'gen_ai.usage.input_tokens.cache_write'],
changelog: [
{ version: 'next', prs: [582], description: 'Added gen_ai.usage.cache_creation_input_tokens attribute' },
],
},
'gen_ai.usage.cache_read.input_tokens': {
brief: 'The number of cached tokens used to process the AI input (prompt).',
type: 'integer',
keys: ['gen_ai.usage.cache_read.input_tokens', 'gen_ai.usage.input_tokens.cached'],
keys: [
'gen_ai.usage.cache_read.input_tokens',
'gen_ai.usage.cache_read_input_tokens',
'gen_ai.usage.input_tokens.cached',
],
applyScrubbing: {
key: 'manual',
},
isInOtel: true,
visibility: 'public',
example: 50,
aliases: ['gen_ai.usage.input_tokens.cached'],
changelog: [{ version: '0.11.0', prs: [418], description: 'Added gen_ai.usage.cache_read.input_tokens attribute' }],
aliases: ['gen_ai.usage.input_tokens.cached', 'gen_ai.usage.cache_read_input_tokens'],
changelog: [
{ version: 'next', description: 'Added gen_ai.usage.cache_read_input_tokens as an alias' },
{ version: '0.11.0', prs: [418], description: 'Added gen_ai.usage.cache_read.input_tokens attribute' },
],
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.cache_read_input_tokens': {
brief: 'The number of cached tokens used to process the AI input (prompt).',
type: 'integer',
keys: [
'gen_ai.usage.cache_read.input_tokens',
'gen_ai.usage.cache_read_input_tokens',
'gen_ai.usage.input_tokens.cached',
],
applyScrubbing: {
key: 'manual',
},
isInOtel: false,
visibility: 'public',
example: 50,
examples: [50],
deprecation: {
replacement: 'gen_ai.usage.cache_read.input_tokens',
reason: 'This attribute is being deprecated in favor of gen_ai.usage.cache_read.input_tokens.',
status: 'backfill',
},
aliases: ['gen_ai.usage.cache_read.input_tokens', 'gen_ai.usage.input_tokens.cached'],
changelog: [{ version: 'next', prs: [582], description: 'Added gen_ai.usage.cache_read_input_tokens attribute' }],
},
'gen_ai.usage.completion_tokens': {
brief: 'The number of tokens used in the GenAI response (completion).',
type: 'integer',
Expand Down Expand Up @@ -26619,7 +26731,11 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
'gen_ai.usage.input_tokens.cached': {
brief: 'The number of cached tokens used to process the AI input (prompt).',
type: 'integer',
keys: ['gen_ai.usage.cache_read.input_tokens', 'gen_ai.usage.input_tokens.cached'],
keys: [
'gen_ai.usage.cache_read.input_tokens',
'gen_ai.usage.cache_read_input_tokens',
'gen_ai.usage.input_tokens.cached',
],
applyScrubbing: {
key: 'manual',
},
Expand All @@ -26630,8 +26746,9 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
replacement: 'gen_ai.usage.cache_read.input_tokens',
status: 'backfill',
},
aliases: ['gen_ai.usage.cache_read.input_tokens'],
aliases: ['gen_ai.usage.cache_read.input_tokens', 'gen_ai.usage.cache_read_input_tokens'],
changelog: [
{ version: 'next', description: 'Added gen_ai.usage.cache_read_input_tokens as an alias' },
{ version: '0.11.0', prs: [418], 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] },
Expand All @@ -26645,7 +26762,11 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
'gen_ai.usage.input_tokens.cache_write': {
brief: 'The number of tokens written to the cache when processing the AI input (prompt).',
type: 'integer',
keys: ['gen_ai.usage.cache_creation.input_tokens', 'gen_ai.usage.input_tokens.cache_write'],
keys: [
'gen_ai.usage.cache_creation.input_tokens',
'gen_ai.usage.cache_creation_input_tokens',
'gen_ai.usage.input_tokens.cache_write',
],
applyScrubbing: {
key: 'manual',
},
Expand All @@ -26656,8 +26777,9 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
replacement: 'gen_ai.usage.cache_creation.input_tokens',
status: 'backfill',
},
aliases: ['gen_ai.usage.cache_creation.input_tokens'],
aliases: ['gen_ai.usage.cache_creation.input_tokens', 'gen_ai.usage.cache_creation_input_tokens'],
changelog: [
{ version: 'next', description: 'Added gen_ai.usage.cache_creation_input_tokens as an alias' },
{ version: '0.11.0', prs: [418], description: 'Deprecate in favor of gen_ai.usage.cache_creation.input_tokens' },
{ version: '0.9.0', prs: [397], description: 'Add additional_context' },
{ version: '0.4.0', prs: [217, 228] },
Expand Down Expand Up @@ -34009,7 +34131,9 @@ export type Attributes = {
[GEN_AI_TOOL_OUTPUT]?: GEN_AI_TOOL_OUTPUT_TYPE;
[GEN_AI_TOOL_TYPE]?: GEN_AI_TOOL_TYPE_TYPE;
[GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS]?: GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS_TYPE;
[_GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS]?: _GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS_TYPE;
[GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS]?: GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS_TYPE;
[_GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS]?: _GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS_TYPE;
[GEN_AI_USAGE_COMPLETION_TOKENS]?: GEN_AI_USAGE_COMPLETION_TOKENS_TYPE;
[GEN_AI_USAGE_INPUT_TOKENS]?: GEN_AI_USAGE_INPUT_TOKENS_TYPE;
[GEN_AI_USAGE_INPUT_TOKENS_CACHED]?: GEN_AI_USAGE_INPUT_TOKENS_CACHED_TYPE;
Expand Down
60 changes: 56 additions & 4 deletions javascript/sentry-conventions/src/search.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2207,11 +2207,25 @@ export const SEARCH_GEN_AI__TOOL__TYPE = 'gen_ai.tool.type';
*/
export const SEARCH_GEN_AI__USAGE__CACHE_CREATION__INPUT_TOKENS = 'gen_ai.usage.cache_creation.input_tokens';

/**
* Search name for {@link attributes._GEN_AI_USAGE_CACHE_CREATION_INPUT_TOKENS}. `gen_ai.usage.cache_creation_input_tokens`
*
* @deprecated Use {@link SEARCH_GEN_AI__USAGE__CACHE_CREATION__INPUT_TOKENS} (`gen_ai.usage.cache_creation.input_tokens`) instead
*/
export const SEARCH_GEN_AI__USAGE__CACHE_CREATION_INPUT_TOKENS = 'gen_ai.usage.cache_creation_input_tokens';

/**
* Search name for {@link attributes.GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS}. `gen_ai.usage.cache_read.input_tokens`
*/
export const SEARCH_GEN_AI__USAGE__CACHE_READ__INPUT_TOKENS = 'gen_ai.usage.cache_read.input_tokens';

/**
* Search name for {@link attributes._GEN_AI_USAGE_CACHE_READ_INPUT_TOKENS}. `gen_ai.usage.cache_read_input_tokens`
*
* @deprecated Use {@link SEARCH_GEN_AI__USAGE__CACHE_READ__INPUT_TOKENS} (`gen_ai.usage.cache_read.input_tokens`) instead
*/
export const SEARCH_GEN_AI__USAGE__CACHE_READ_INPUT_TOKENS = 'gen_ai.usage.cache_read_input_tokens';

/**
* Search name for {@link attributes.GEN_AI_USAGE_COMPLETION_TOKENS}. `gen_ai.usage.completion_tokens`
*
Expand Down Expand Up @@ -5213,7 +5227,9 @@ export type AttributeSearchName =
| typeof SEARCH_GEN_AI__TOOL__OUTPUT
| typeof SEARCH_GEN_AI__TOOL__TYPE
| typeof SEARCH_GEN_AI__USAGE__CACHE_CREATION__INPUT_TOKENS
| typeof SEARCH_GEN_AI__USAGE__CACHE_CREATION_INPUT_TOKENS
| typeof SEARCH_GEN_AI__USAGE__CACHE_READ__INPUT_TOKENS
| typeof SEARCH_GEN_AI__USAGE__CACHE_READ_INPUT_TOKENS
| typeof SEARCH_GEN_AI__USAGE__COMPLETION_TOKENS
| typeof SEARCH_GEN_AI__USAGE__INPUT_TOKENS
| typeof SEARCH_GEN_AI__USAGE__INPUT_TOKENS__CACHE_WRITE
Expand Down Expand Up @@ -8177,13 +8193,41 @@ export const ATTRIBUTE_SEARCH_METADATA: Record<string, AttributeSearchMetadata>
canonicalName: 'gen_ai.usage.cache_creation.input_tokens',
type: 'integer',
brief: 'The number of tokens written to the cache when processing the AI input (prompt).',
deprecationChain: ['gen_ai.usage.cache_creation.input_tokens', 'gen_ai.usage.input_tokens.cache_write'],
deprecationChain: [
'gen_ai.usage.cache_creation.input_tokens',
'gen_ai.usage.cache_creation_input_tokens',
'gen_ai.usage.input_tokens.cache_write',
],
},
'gen_ai.usage.cache_creation_input_tokens': {
canonicalName: 'gen_ai.usage.cache_creation.input_tokens',
type: 'integer',
brief: 'The number of tokens written to the cache when processing the AI input (prompt).',
deprecationChain: [
'gen_ai.usage.cache_creation.input_tokens',
'gen_ai.usage.cache_creation_input_tokens',
'gen_ai.usage.input_tokens.cache_write',
],
},
'gen_ai.usage.cache_read.input_tokens': {
canonicalName: 'gen_ai.usage.cache_read.input_tokens',
type: 'integer',
brief: 'The number of cached tokens used to process the AI input (prompt).',
deprecationChain: ['gen_ai.usage.cache_read.input_tokens', 'gen_ai.usage.input_tokens.cached'],
deprecationChain: [
'gen_ai.usage.cache_read.input_tokens',
'gen_ai.usage.cache_read_input_tokens',
'gen_ai.usage.input_tokens.cached',
],
},
'gen_ai.usage.cache_read_input_tokens': {
canonicalName: 'gen_ai.usage.cache_read.input_tokens',
type: 'integer',
brief: 'The number of cached tokens used to process the AI input (prompt).',
deprecationChain: [
'gen_ai.usage.cache_read.input_tokens',
'gen_ai.usage.cache_read_input_tokens',
'gen_ai.usage.input_tokens.cached',
],
},
'gen_ai.usage.completion_tokens': {
canonicalName: 'gen_ai.usage.output_tokens',
Expand All @@ -8201,13 +8245,21 @@ export const ATTRIBUTE_SEARCH_METADATA: Record<string, AttributeSearchMetadata>
canonicalName: 'gen_ai.usage.cache_creation.input_tokens',
type: 'integer',
brief: 'The number of tokens written to the cache when processing the AI input (prompt).',
deprecationChain: ['gen_ai.usage.cache_creation.input_tokens', 'gen_ai.usage.input_tokens.cache_write'],
deprecationChain: [
'gen_ai.usage.cache_creation.input_tokens',
'gen_ai.usage.cache_creation_input_tokens',
'gen_ai.usage.input_tokens.cache_write',
],
},
'gen_ai.usage.input_tokens.cached': {
canonicalName: 'gen_ai.usage.cache_read.input_tokens',
type: 'integer',
brief: 'The number of cached tokens used to process the AI input (prompt).',
deprecationChain: ['gen_ai.usage.cache_read.input_tokens', 'gen_ai.usage.input_tokens.cached'],
deprecationChain: [
'gen_ai.usage.cache_read.input_tokens',
'gen_ai.usage.cache_read_input_tokens',
'gen_ai.usage.input_tokens.cached',
],
},
'gen_ai.usage.output_tokens': {
canonicalName: 'gen_ai.usage.output_tokens',
Expand Down
Loading
Loading