feat(ai): add input tokens cache write (#217)

Add the new attribute gen_ai.usage.input_tokens.cache_write to record cached writes

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

Author: shellmayr

CHANGELOG.md

@@ -6,6 +6,7 @@
 
 #### Changes to attributes
 
+- feat(ai): Add gen_ai.usage.input_tokens.cache_write ([#217](https://github.com/getsentry/sentry-conventions/pull/217))
 - feat(attributes): Add sentry.normalized_db_query.hash ([#200](https://github.com/getsentry/sentry-conventions/pull/200))
 
 ## 0.3.1

generated/attributes/all.md

@@ -4,7 +4,7 @@
 
 This page lists all available attributes across all categories.
 
-Total attributes: 413
+Total attributes: 414
 
 ## Stable Attributes
 
@@ -110,6 +110,7 @@ Total attributes: 413
 | [`gen_ai.tool.output`](./gen_ai.md#gen_aitooloutput) | The output of the tool being used. It has to be a stringified version of the output of the tool. |
 | [`gen_ai.tool.type`](./gen_ai.md#gen_aitooltype) | The type of tool being used. |
 | [`gen_ai.usage.input_tokens`](./gen_ai.md#gen_aiusageinput_tokens) | The number of tokens used to process the AI input (prompt) without cached input tokens. |
+| [`gen_ai.usage.input_tokens.cache_write`](./gen_ai.md#gen_aiusageinput_tokenscache_write) | The number of tokens written to the cache when processing the AI input (prompt). |
 | [`gen_ai.usage.input_tokens.cached`](./gen_ai.md#gen_aiusageinput_tokenscached) | The number of cached tokens used to process the AI input (prompt). |
 | [`gen_ai.usage.output_tokens`](./gen_ai.md#gen_aiusageoutput_tokens) | The number of tokens used for creating the AI output (without reasoning tokens). |
 | [`gen_ai.usage.output_tokens.reasoning`](./gen_ai.md#gen_aiusageoutput_tokensreasoning) | The number of tokens used for reasoning to create the AI output. |

generated/attributes/gen_ai.md

@@ -39,6 +39,7 @@
   - [gen_ai.tool.output](#gen_aitooloutput)
   - [gen_ai.tool.type](#gen_aitooltype)
   - [gen_ai.usage.input_tokens](#gen_aiusageinput_tokens)
+  - [gen_ai.usage.input_tokens.cache_write](#gen_aiusageinput_tokenscache_write)
   - [gen_ai.usage.input_tokens.cached](#gen_aiusageinput_tokenscached)
   - [gen_ai.usage.output_tokens](#gen_aiusageoutput_tokens)
   - [gen_ai.usage.output_tokens.reasoning](#gen_aiusageoutput_tokensreasoning)
@@ -462,6 +463,17 @@ The number of tokens used to process the AI input (prompt) without cached input
 | Example | `10` |
 | Aliases | `ai.prompt_tokens.used`, `gen_ai.usage.prompt_tokens` |
 
+### gen_ai.usage.input_tokens.cache_write
+
+The number of tokens written to the cache when processing the AI input (prompt).
+
+| Property | Value |
+| --- | --- |
+| Type | `integer` |
+| Has PII | false |
+| Exists in OpenTelemetry | No |
+| Example | `100` |
+
 ### gen_ai.usage.input_tokens.cached
 
 The number of cached tokens used to process the AI input (prompt).

javascript/sentry-conventions/src/attributes.ts

@@ -2819,6 +2819,26 @@ export const GEN_AI_USAGE_INPUT_TOKENS_CACHED = 'gen_ai.usage.input_tokens.cache
  */
 export type GEN_AI_USAGE_INPUT_TOKENS_CACHED_TYPE = number;
 
+// Path: model/attributes/gen_ai/gen_ai__usage__input_tokens__cache_write.json
+
+/**
+ * The number of tokens written to the cache when processing the AI input (prompt). `gen_ai.usage.input_tokens.cache_write`
+ *
+ * Attribute Value Type: `number` {@link GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE_TYPE}
+ *
+ * Contains PII: false
+ *
+ * Attribute defined in OTEL: No
+ *
+ * @example 100
+ */
+export const GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE = 'gen_ai.usage.input_tokens.cache_write';
+
+/**
+ * Type for {@link GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE} gen_ai.usage.input_tokens.cache_write
+ */
+export type GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE_TYPE = number;
+
 // Path: model/attributes/gen_ai/gen_ai__usage__output_tokens.json
 
 /**
@@ -8757,6 +8777,7 @@ export const ATTRIBUTE_TYPE: Record<string, AttributeType> = {
   [GEN_AI_USAGE_COMPLETION_TOKENS]: 'integer',
   [GEN_AI_USAGE_INPUT_TOKENS]: 'integer',
   [GEN_AI_USAGE_INPUT_TOKENS_CACHED]: 'integer',
+  [GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE]: 'integer',
   [GEN_AI_USAGE_OUTPUT_TOKENS]: 'integer',
   [GEN_AI_USAGE_OUTPUT_TOKENS_REASONING]: 'integer',
   [GEN_AI_USAGE_PROMPT_TOKENS]: 'integer',
@@ -9173,6 +9194,7 @@ export type AttributeName =
   | typeof GEN_AI_USAGE_COMPLETION_TOKENS
   | typeof GEN_AI_USAGE_INPUT_TOKENS
   | typeof GEN_AI_USAGE_INPUT_TOKENS_CACHED
+  | typeof GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE
   | typeof GEN_AI_USAGE_OUTPUT_TOKENS
   | typeof GEN_AI_USAGE_OUTPUT_TOKENS_REASONING
   | typeof GEN_AI_USAGE_PROMPT_TOKENS
@@ -10873,6 +10895,15 @@ export const ATTRIBUTE_METADATA: Record<AttributeName, AttributeMetadata> = {
     isInOtel: false,
     example: 50,
   },
+  [GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE]: {
+    brief: 'The number of tokens written to the cache when processing the AI input (prompt).',
+    type: 'integer',
+    pii: {
+      isPii: 'false',
+    },
+    isInOtel: false,
+    example: 100,
+  },
   [GEN_AI_USAGE_OUTPUT_TOKENS]: {
     brief: 'The number of tokens used for creating the AI output (without reasoning tokens).',
     type: 'integer',
@@ -13812,6 +13843,7 @@ export type Attributes = {
   [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;
+  [GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE]?: GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE_TYPE;
   [GEN_AI_USAGE_OUTPUT_TOKENS]?: GEN_AI_USAGE_OUTPUT_TOKENS_TYPE;
   [GEN_AI_USAGE_OUTPUT_TOKENS_REASONING]?: GEN_AI_USAGE_OUTPUT_TOKENS_REASONING_TYPE;
   [GEN_AI_USAGE_PROMPT_TOKENS]?: GEN_AI_USAGE_PROMPT_TOKENS_TYPE;

model/attributes/gen_ai/gen_ai__usage__input_tokens__cache_write.json

@@ -0,0 +1,10 @@
+{
+  "key": "gen_ai.usage.input_tokens.cache_write",
+  "brief": "The number of tokens written to the cache when processing the AI input (prompt).",
+  "type": "integer",
+  "pii": {
+    "key": "false"
+  },
+  "is_in_otel": false,
+  "example": 100
+}

python/src/sentry_conventions/attributes.py

@@ -1639,6 +1639,18 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
     Example: 10
     """
 
+    # Path: model/attributes/gen_ai/gen_ai__usage__input_tokens__cache_write.json
+    GEN_AI_USAGE_INPUT_TOKENS_CACHE_WRITE: Literal[
+        "gen_ai.usage.input_tokens.cache_write"
+    ] = "gen_ai.usage.input_tokens.cache_write"
+    """The number of tokens written to the cache when processing the AI input (prompt).
+
+    Type: int
+    Contains PII: false
+    Defined in OTEL: No
+    Example: 100
+    """
+
     # Path: model/attributes/gen_ai/gen_ai__usage__input_tokens__cached.json
     GEN_AI_USAGE_INPUT_TOKENS_CACHED: Literal["gen_ai.usage.input_tokens.cached"] = (
         "gen_ai.usage.input_tokens.cached"
@@ -5765,6 +5777,13 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
         example=10,
         aliases=["ai.prompt_tokens.used", "gen_ai.usage.prompt_tokens"],
     ),
+    "gen_ai.usage.input_tokens.cache_write": AttributeMetadata(
+        brief="The number of tokens written to the cache when processing the AI input (prompt).",
+        type=AttributeType.INTEGER,
+        pii=PiiInfo(isPii=IsPii.FALSE),
+        is_in_otel=False,
+        example=100,
+    ),
     "gen_ai.usage.input_tokens.cached": AttributeMetadata(
         brief="The number of cached tokens used to process the AI input (prompt).",
         type=AttributeType.INTEGER,
@@ -8070,6 +8089,7 @@ class ATTRIBUTE_NAMES(metaclass=_AttributeNamesMeta):
         "gen_ai.tool.type": str,
         "gen_ai.usage.completion_tokens": int,
         "gen_ai.usage.input_tokens": int,
+        "gen_ai.usage.input_tokens.cache_write": int,
         "gen_ai.usage.input_tokens.cached": int,
         "gen_ai.usage.output_tokens": int,
         "gen_ai.usage.output_tokens.reasoning": int,