OTel 分清 5 分钟和 1 小时缓存写入：cache_creation_5m / 1h_tokens

提示缓存（prompt cache）能省后续轮次的输入成本，但「写入缓存」本身也有代价，而且 5 分钟 TTL 和 1 小时 TTL 的写入单价、过期节奏都不一样。以前在 OpenTelemetry 里，若只看一团「cache creation」总量，很难回答：

• 团队主要在写短 TTL 还是长 TTL？
• 空闲压缩、长会话是不是把大量写入推到了 1 小时桶？
• 成本报表里的 cache write 该按哪档单价估算？

CLI 2.1.300 在 OpenTelemetry 的 api_request 事件里加了两个字段：

• cache_creation_5m_tokens
• cache_creation_1h_tokens

把按生命周期拆开的缓存写入 token 数直接打进遥测。

字段分别表示什么

字段	含义
cache_creation_5m_tokens	本次 API 请求里，写入 5 分钟 提示缓存的 token 数
cache_creation_1h_tokens	本次 API 请求里，写入 1 小时 提示缓存的 token 数

它们是对「这次请求创建了多少缓存」的拆分，不是「读缓存省了多少」（读缓存一般有单独的 cache read 类指标）。一次请求可能只写其中一种，也可能两种都有，取决于当前会话用的缓存策略与 Anthropic 侧实际落盘结果。

为什么值得看

1. 对账更准

5 分钟与 1 小时缓存写入的价格不同。报表若只看合计，容易把贵的一档和便宜的一档混在一起。拆开之后，可以按官方单价分别乘，再和账单对照。

2. 解释「为什么这笔会话特别贵」

长对话反复触发缓存重建、或频繁切换模型导致前缀对不齐时，你会看到 creation 数字飙高。若飙高的是 1h，说明在付长 TTL 写入；若主要是 5m，则是短窗写入在抖——排查方向不同。

3. 和空闲压缩等产品行为对照

例如终端里的 idle compaction 会赶在一小时缓存过期前压缩，目的之一就是少付「过期后再当全新输入处理」的成本。有了按 TTL 拆开的 creation 指标，你可以在仪表盘上验证：启用空闲压缩前后，1h 写入与后续 cache miss 是否按预期变化。

怎么用上（前提）

需要先打开 Claude Code 的 OpenTelemetry 导出（具体变量以当前版本文档为准，常见是启用 telemetry 并配置 OTLP endpoint）。项目级 settings 不一定能打开导出类 OTEL——若 /status 或 claude doctor 提示变量被忽略，把导出相关配置放到用户级或环境里，参见站内 遥测排查文。

字段就绪后，在你的后端（Grafana、Datadog、自建 collector 等）对 api_request 事件做：

• 按天 / 按用户 / 按仓库聚合 cache_creation_5m_tokens 与 cache_creation_1h_tokens；
• 分别乘对应单价，得到「缓存写入成本」估算；
• 与 cache read、普通 input tokens 放在同一张图上，看比例。

同版本相关遥测

2.1.300 还为 trace span 补了一批 GenAI 语义约定属性（如 gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name、error.type 等）。若你在做全链路追踪，可以和上述 cache 字段一起用：span 上看「哪次对话、哪个工具出错」，api_request 上看「这次请求写了多少 5m/1h 缓存」。

小结

• 2.1.300：api_request 新增 cache_creation_5m_tokens / cache_creation_1h_tokens；
• 用途：按 TTL 拆开缓存写入量，便于计费与优化；
• 不替代修上下文策略——指标告诉你「写了多少」，省钱仍靠少重建、对齐前缀、合理压缩。

已经在跑 Claude Code OTEL 的团队，升级后检查一下导出管道是否映射了这两个新属性；没有的话，补上字段映射就能开始分桶看图。