AI 原生开放教材

外观

How Claude Code Works源码研读·中文原文 ↗仓库 ↗

第 16 章：可观测性——一次任务的全程可追溯 ​

分布式数据库能对一条 SQL 做 EXPLAIN，把它拆成算子：走了哪些步、每步读多少行、花多久、有没有倾斜。Claude Code 对它自己做的是同一件事——你交给它一个任务，它跨多个 turn 完成，每个 turn 打了哪些 API、调了哪些工具、花了多少 token 和钱、在哪等你批权限、有没有报错重试，全被记下来、能串成一条链回放。这一章讲它怎么做到，以及为什么这么设计。

16.1 三类问题，四种记录 ​

先看要解决的问题。你让 Claude Code 修个 bug，它不是“调一次模型”就完事，而是跑一串 turn：读文件、定位、改、等你批、执行、跑测试、总结。事后你可能想查三类完全不同的东西：

  • 这个月团队一共花了多少钱、多少 token？你要的是能累加的数字，不关心是哪一次 prompt 产生的。
  • 上周那次 git push 是谁批的？你要的是能按条件筛的一条条离散记录。
  • 这次修 bug 的七八步里，哪一步最慢、卡在哪？你要的是带父子关系、带耗时的一棵调用树，也就是 EXPLAIN 里那棵算子树。

三类问题，数据结构完全不同——能聚合的计数器、可查询的事件流、有嵌套的追踪树。混在一个大日志里，哪类都查不好。所以 Claude Code 把可观测性拆成对应的几层，每层只干一件事。

具体是四层：前三层是标准的 OpenTelemetry 三件套（指标 / 事件 / 追踪），第四层是它每次运行都往硬盘写的会话记录。

  • 指标（Metrics）回答“总账”类问题——一堆只增不减的计数器：会话数、token、花费、改动行数。为了能被时序库高效聚合，它刻意只带很粗的维度（模型名、token 类型），绝不带每次 prompt 的 ID：否则维度爆炸，库就被拖垮。这条“聚合层拒绝高基数 ID”的红线后面会反复出现。
  • 事件（Events）回答“某件事”类问题。每打一次 API、每调一个工具、每做一次权限决策，都留一条带时间戳的离散记录，你能按 prompt、按工具、按结果去筛。
  • 追踪（Trace）回答“整条链”类问题。它把一次任务建成一棵树：一次交互是根，底下挂着每个 turn 的模型调用、每次工具执行、还有“卡在等你批权限”那段时间，每个节点都带耗时。这是最贴近 EXPLAIN 的一层，但它默认关着、还在 beta，原因后面讲。
  • 会话记录（Transcript）是那份“默认就在、人人都有”的追踪。前三层要你主动开遥测、配后端才看得到；而每次运行，CC 都会往 ~/.claude/projects/ 写一个 JSONL，把每条消息、每次 token 用量、消息间的父子关系都记下来——/resume 靠它，社区分析工具也靠它。对绝大多数人，这才是实际用得上的那份 trace。

怎么把一次 prompt 的数据从四层里拼回一条链 ​

四层各记各的，但你查问题时想要的是“这一次 prompt 的全部账”。把它们对齐到同一次 prompt，靠一个关联锚点：一个 UUID。

用户输入进来时，CC 先生成这个 UUID（叫 prompt.id），存进全局状态，然后在同一处代码里做两件事——开一棵追踪树的根，发一条 user_prompt 事件。也就是说，追踪和事件从一开始就被挂到了同一次 prompt 上：

typescript
// utils/processUserInput/processTextPrompt.ts:31
const promptId = randomUUID()
setPromptId(promptId)
startInteractionSpan(userPromptText)          // 开追踪树的根
void logOTelEvent('user_prompt', { /* … */ 'prompt.id': promptId })

但四层用这个 id 的方式并不一样，说清楚这点很重要，否则容易以为它是平铺在四层的同一个字段：

  • 事件层：每条事件都自动带 prompt.id（events.ts:49）。这是它真正的关联键，同一次 prompt 的所有事件靠它归拢。
  • 会话记录层：prompt.id 只盖在“用户消息”那种行上（用户输入行、以及工具结果回注的行，这两种在内部都算 user 类型），assistant 行不带。所以它是这次 prompt 在本地记录里的一个锚点，帮你定位起点，不是能把所有相关消息一网打尽的分组键。
  • 追踪层：span 根本不带 prompt.id。一次交互内部的父子关系不靠 id，靠“谁是谁的父 span”这种树形归属来表达（全都挂在 claude_code.interaction 这个根下，见 16.4）。它和事件、记录指的是同一次 prompt，纯粹因为三者是同一处代码同时开的。
  • 指标层：故意一个 prompt 级 id 都不带（events.ts:49 注释直说，否则会 unbounded cardinality）。

离散层用 id 关联、因果层用树形归属、聚合层拒绝 id——这条分界是整套设计的第一性原则。记住它，后面每一层都在贯彻它。

下面四节分头拆这四层。

16.2 指标：一个开关，两条管线 ​

指标面有个容易看漏的地方：它同时喂两条互不相干的管线，各由不同的开关控制。

一条是给你自己的。你设 CLAUDE_CODE_ENABLE_TELEMETRY，CC 就把指标按标准 OTLP 协议送到你自己的 Prometheus 或 collector（instrumentation.ts:324），企业拿它给团队做用量看板。另一条是给 Anthropic 的：面向 API 客户、企业版、团队版，指标会送进 Anthropic 自己的 BigQuery（isBigQueryMetricsEnabled，instrumentation.ts:336），供官方做产品分析。

两条独立。哪怕你没开 CLAUDE_CODE_ENABLE_TELEMETRY，BigQuery 那条也可能在跑——它由组织级的 opt-out 单独控制。想清楚这点，才不会把“我没开遥测”误当成“什么都没上报”。

别让上报把主流程拖垮 ​

BigQuery 这条在每次导出前都要确认一句“这个组织允许上报吗”。最直白的写法是每次导出都打一次 API，但 claude -p 这种一次性调用一天可能跑几百次，那样启动路径和网络都受不了。CC 的做法是拿两级缓存把它压成“大约一天一次 API”：进程内一个一小时 TTL 的内存缓存去重，磁盘上再放一个 24 小时 TTL 的缓存跨进程存活（metricsOptOut.ts:22，注释原话就是这级缓存把 N 次 claude -p 折叠成每天约一次 API）。缓存新鲜就零网络返回，过期才后台异步刷新。上面还压了一道熔断：一旦“非必要流量被全局关闭”，直接返回未启用、在消费端就把导出停掉（metricsOptOut.ts:57）。

这背后是一条能推广的工程判断：可观测性本身不能成为负担。观测组件必须能被廉价地关掉、能容忍读到陈旧值、且默认不阻塞主流程。

八个指标，一个稳定的底座 ​

CC 内部注册的指标只有八个，都是只增不减的计数器（bootstrap/state.ts:955）：启动的会话数、改动的代码行数、创建的 PR 数与 commit 数、会话花费（美元）、token 数、代码编辑工具的批/拒计数、活跃秒数。

两个细节值得留意。一是这八个和官方 Monitoring 文档的清单逐条对齐——这是个难得的“快照即当前”的稳定点，下一节会看到事件清单正好相反，快照之后猛涨。二是它们全用计数器而不用瞬时值（gauge）：计数器对采样丢失、进程重启、乱序到达都更鲁棒，聚合时只要做差值，CC 甚至默认把时序偏好设成 delta（instrumentation.ts:113，注释说这才是更合理的默认）。

还要注意指标只带“形状”不带内容。token 计数带 type（input/output/cacheRead/cacheCreation）和模型名，但绝不带 prompt 文本；代码行计数带 added/removed，但绝不带文件路径或代码。这不是疏忽，是刻意，理由见 16.8。

把基数当旋钮 ​

每条指标该带哪些公共属性，本身也是可配的——因为“多带一个属性”往往就等于“时序库多切一个维度”。CC 把最危险的几个做成开关，默认值就透着克制（telemetryAttributes.ts:10）：session.id 默认带，app.version 默认不带。

app.version 默认关的理由，和指标拒绝 prompt.id 是同一个：CC 周更，要是每个版本号都成为一个新维度，时序库会被版本切得粉碎。把这些交给 env 开关，等于把“我要多细的归因”和“我能扛多大的基数”之间的取舍权交给运维。可观测性设计里，这个取舍会一次次出现。

（另有一个不起眼但值得学的细节：OTLP 的三种协议 exporter 加起来约 1.2MB，CC 没在启动时全静态导入，而是在协议分支里按需 await import()——把“只有开了遥测、且用某协议才需要”的重依赖挪出冷启动关键路径，instrumentation.ts:3。CLI 对启动延迟很敏感，这类纪律随处可见。）

16.3 事件：一处代码，两条事件流 ​

理解 CC 遥测的第二个关键，是“内部分析”和“客户可观测”是两条并行的事件流，而且常常从同一处代码同时发出。API 成功那一瞬间，这处代码连发三样东西：一条内部分析事件（去 Anthropic 的 Statsig/Datadog/BigQuery），一条客户 OTel 事件（去你自己的 OTLP 后端），再结束这次请求对应的追踪 span。

typescript
// services/api/logging.ts（API 成功时）
logEvent('tengu_api_success', { model, inputTokens, outputTokens, costUSD, … })  // 内部分析
void logOTelEvent('api_request', { model, input_tokens, output_tokens, … })       // 客户可观测
endLLMRequestSpan(llmSpan, { success: true, inputTokens, … })                     // 结束 trace span

两条流分工清楚。内部这条（名字都以 tengu_ 打头）去向 Anthropic，供官方做产品分析、A/B、行为回归，数量上有数百个事件名，由 feature flag 加采样门控。客户那条（logOTelEvent）去你自己的后端，供你给团队做用量和健康看板，就官方文档化的一二十类，由 CLAUDE_CODE_ENABLE_TELEMETRY 门控。

内部这条有个有意思的类型级护栏：logEvent 不收裸字符串，任何要传的字符串都得显式断言成一个名字很长的类型——AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS（services/analytics/index.ts:19）。等于用编译期类型把“别把代码或文件名误传进分析后台”变成一条过不了 CI 的硬约束。真要传 PII，得走 _PROTO_ 前缀，路由进有访问控制的 BigQuery 专列，并在扇出到 Datadog 前统一剥掉（index.ts:45）。

每条客户事件的骨架 ​

客户侧事件都走 logOTelEvent（events.ts:21），它给每条事件盖三个信封字段：事件名、时间戳，和一个会话内单调递增的 event.sequence。

event.sequence 值得单说一句，因为容易误解：它是个发射计数器，每发一条加一，作用是让后端在批处理和网络打乱了到达顺序之后，还能把一次 prompt 内的事件按发射先后排回来。它不是墙钟时刻——并发或重叠的 API 与工具活动谁真正先发生、各持续多久，那要看时间戳和下一节的 span 耗时。event.sequence 只保证一件事：离散事件的发射次序可恢复。

快照里有哪些事件，如今又多了多少 ​

在 v2.1.88 快照里，实际发出的客户事件是这几类：user_prompt、api_request、api_error、tool_result、tool_decision，加上 beta 详细追踪下的 system_prompt、tool，以及 hook 的开始/结束和一条问卷事件。

当前官方文档的清单已经明显扩张，多出 assistant_response、compaction、skill_activated、permission_mode_changed、api_request_body/api_response_body、mcp_server_connection、plugin_loaded 等一批。

一条口径说明：本章 metric 清单（8 个）在快照与官方文档间稳定一致，但事件清单在 v2.1.88 之后长了不少。凡提到那些在快照里 grep 不到的标识符（assistant_response、OTEL_LOG_RAW_API_BODIES 等），一律以官方 Monitoring 文档为准，注明是“据官方文档”，不当成从快照源码里直接读到的事实。

用 api_request 看一次调用 ​

拿最能回答读者的 api_request 说（logging.ts:718）。它在每次 API 成功后发一条，带模型名、input/output/缓存读/缓存写各多少 token、花了多少钱、耗时多久、快慢档。把一次 prompt 里所有带同一 prompt.id 的 api_request 按 event.sequence 排好，你就拿到这条 prompt 的一份模型调用流水：一共打了几次 API、各花多少 token 和钱、命中多少缓存、多久。tool_decision 和 tool_result 再补上“工具被怎么放行/拦截”和“工具跑了多久、成没成、结果多大”。三类拼起来，一次 prompt 的对外动作总账就有了。

但要老实标一条边界。在 v2.1.88 快照里，这些事件是按 prompt 关联、不是按 turn 关联的：api_request 不带 turn 序号，tool_decision 和 tool_result 也不带 tool_use_id（当前版本才给它们加上）。所以“哪个 tool_result 对应哪次 api_request、哪个 turn”这种精确因果，光靠事件字段在快照里拼不出来——那是下一节 span 树和会话记录的父子边负责的事。事件层给的是“这次 prompt 的有序动作流水”，因果树留给追踪层。

16.4 追踪：一次交互的算子树，加一份人人都有的记录 ​

这是全章重心，也最贴近“对一次任务做 EXPLAIN”的诉求。它由两套东西共同承担：一套是 OpenTelemetry 的 span 树（精确因果，但默认关、还在 beta），一套是本地会话记录（默认就开、人人都有）。

(A) span 树：把一次交互建成一棵算子树 ​

CC 定义了六种 span，它们的父子关系摆出来，正好就是一棵 EXPLAIN 算子树：

claude_code.interaction              根：一次用户 prompt 到回复的完整周期
  ├─ claude_code.llm_request         每个 turn 的一次模型调用
  ├─ claude_code.tool                一次工具调用
  │    ├─ …tool.blocked_on_user      卡在“等你批权限”的墙钟时间
  │    └─ …tool.execution            工具真正执行的时间
  └─ claude_code.hook                一次 hook 执行（仅 beta 详细追踪）

（类型定义见 sessionTracing.ts:49。）根就是 16.1 那个在 prompt 一进来时开的 startInteractionSpan，结束时补上整段耗时。父子关系怎么建立的？靠 AsyncLocalStorage：交互 span 存进去，之后开子 span 时从里面取出当前父 span——这样哪怕中间隔着好几层异步 await，子 span 也能正确挂到当前交互底下，而不用一路手动传句柄。

三个设计细节特别能说明“追踪要做对不容易”。

第一，把“等你批权限”单独计时。为什么给这段专门开一个 tool.blocked_on_user span？因为一次 Edit 慢，可能是模型慢、可能是磁盘慢，也可能纯粹是你去倒了杯咖啡。把“等人”从“执行”里剥出来，才能在追踪里一眼看清墙钟时间到底花在哪儿——这直接决定你该去优化模型、优化 IO，还是优化工作流。这段结束时还会记下批还是拒、谁批的，数据来自权限层（见 16.6）。

第二，并发请求必须显式传 span。一次交互里常有好几个模型请求同时在打（主线程、预热、话题分类器、路径抽取器）。代码注释专门警告：回填响应时如果不把当初那个 span 显式带上，就可能挂到“恰好最后开的那个”span 上，造成响应错配（sessionTracing.ts:342）。这是并发追踪里最经典的坑，CC 用“显式传句柄”而不是“隐式取最近”来根治。

第三，给 span 泄漏兜底。正常路径会及时结束并删除 span，但流被中断、turn 中途抛异常时，span 可能永远不 end。CC 用弱引用存活跃 span，再挂一个半小时的后台清理，把没人引用或超时的强制回收——观测设施自己不能变成内存泄漏源。

每个 span 结束都带耗时，模型 span 还带 token 明细。于是这棵树天然就是一份带耗时和消耗的 EXPLAIN：哪个 turn、哪次工具、哪段等待最贵，一目了然。

那它为什么默认关、还挂着 beta？因为它又贵又敏感。开启要同时满足“遥测已开”和“增强追踪已开”，后者还得编译期把这个特性编进去、运行时再放行。更详细的 beta 路径连 system prompt、模型输出都往 span 里写，门槛更高、还带脱敏。span 数量随工具调用线性涨、又背着不少属性，默认开会同时压上性能和隐私两笔账。

(B) 会话记录：那份默认就在的追踪 ​

如果说 span 树是“要专门开、给后端看”的追踪，那会话记录就是“day-0 就在、每个人本地都有”的那份。前者要你开遥测配后端，后者每次运行都自动往 ~/.claude/projects/<把工作目录转义成的目录名>/<会话 id>.jsonl 写。/resume 读它，社区几乎所有分析工具也读它。对绝大多数人，这才是真正用得上的那份 trace。子 agent 另写自己的文件，每条委派链的追踪互相分开。

它本质是一个用 parentUuid 串起来的链表：每写一条消息，都盖上一批字段，其中 parentUuid 指向上一条。三个精妙处：

  • 工具结果的父指针，指向发起它的那条 assistant 消息，而不是简单的“物理上一条”。代码专门处理这点（sessionStorage.ts:1031）。于是某个工具结果能精确回溯到“哪个 assistant turn 里的哪次调用请求了它”——因果是显式连边，不是靠时间顺序去猜。
  • 压缩边界断物理链、但留逻辑链。上下文压缩会把一段历史换成摘要，这时 parentUuid 置空（物理断开，好让 prompt 缓存稳定），但另存一个 logicalParentUuid 保住原来的父指针，读的时候再桥接。压缩不破坏追踪的逻辑连续性。
  • promptId 只盖在用户消息上，正是 16.1 那个锚点在硬盘上的落点。

那怎么从这份记录里重建“一次 prompt 的多个 turn”？主力是沿 parentUuid 走连边：从任意一条消息回溯到根，或从起点往下顺子边展开，就能把 assistant turn、它发起的工具调用、以及回来的结果层层连起来。promptId 在这里是定位锚点，不是分组键——它只在 user 行上，所以你用它找到某次 prompt 的起点，再靠 parentUuid 把这次的 assistant 和工具因果走出来；单纯“按 promptId 分组”会漏掉不带它的 assistant 行，收不齐。这就是会话记录版的 EXPLAIN，而且它默认就躺在你硬盘上，一个遥测都不用开。

用户也不必手动去解析 JSONL：/cost 汇总本次会话的 token、成本、时长（见 16.5），/status、/context 看别的维度，--debug 打开调试日志。社区那些按 transcript 算用量、抓请求的工具，也都建在这份记录或其等价数据上。

活例子：/goal 和 /loop 怎么被追踪 ​

抽象讲完，用两个真实功能落一下地。以下来自对 2.1.201 客户端的逆向（静态抽字符串加抓包），是快照之后的东西，单独说明，跟前面基于 v2.1.88 快照的内容分开、不混为一谈。

/goal（让 Claude 盯着一个目标反复干到达成）自带追踪字段。你设一个目标后，会话记录里会挂一条 goal_status，字段是条件、迭代了几轮、耗时、烧了多少 token、达成没——每一轮的进度都累计进去。它的机制是一个每轮结束就触发的 Stop hook，派一个独立的小模型判“达没达成”，判词和计数都落进这条记录。

/loop（按间隔或自定节奏反复跑一个 prompt）则靠一串带语义的事件追踪每次触发：调度了下一次唤醒、这次唤醒结束了一个 turn、太久没动被回收、保活触发、循环结束，再加上后台调度守护进程的一族事件。每次循环重投同一个 prompt，都在这条事件流里留痕。

两个例子说明同一件事：CC 的“跨多个 turn 的一次任务”不是黑盒——要么落成会话记录里的结构化字段（goal），要么落成一串带语义的事件（loop），都能重建“这次自治跑了几轮、每轮什么状态”。这两个功能的完整逆向见第 17 章。

16.5 成本：不是一个总数，是一路累加 ​

/cost 那块摘要背后，是每次 API 成功就即时累加的账。每成功一次，这次的用量就累进按模型分的汇总，同时喂给两个计数器——花费一个，token 一个（cost-tracker.ts:291）。

token 被拆成 input、output、缓存读、缓存写四类分开计，因为四类单价不同：缓存读命中远比新输入便宜，不分开就算不准钱。CC 甚至给内部的 advisor 子调用单独计费、单发一条事件，确保派生调用的成本不漏。

这笔账还能跨会话接续：成本状态存进项目配置，/resume 同一个会话时按会话 id 恢复，续跑不会从零开始。进程退出时打印总账并存盘，就是你在终端看到的那块“总花费 / API 与墙钟耗时 / 代码改动 / 各模型用量”。

所以这一节回答的是 EXPLAIN 里“每一环消耗多少资源”：token 和钱不是一个事后总数，而是每次调用即时累加、按模型和类型分维、还能跨 resume 接着算的运行量。

16.6 权限决策：把“为什么放行”也记下来 ​

EXPLAIN 里还有一环——每个动作是否正常、有没有被拦。CC 把每一次工具权限决策都记成可观测数据，核心是一个叫 logPermissionDecision 的函数，它是所有“批准 / 拒绝”的唯一出口，一次决策扇出到四个地方（permissionLogging.ts:181）：按来源分成不同名字的内部分析事件（做审批漏斗），给代码编辑工具的计数器加一，把决策写回工具上下文供追踪层读，再发一条客户 OTel 事件。

有观测价值的是它把“谁批的”结构化成了 source 字段：配置里 allowlist 自动放的、hook 放的、你点“总是”或“这次”放的、分类器放的、你拒的、你中止的。安全复盘时，你能一眼分清“这次危险操作是人手动放的，还是规则自动放的”——这往往是决定性的。它还把“等人”量化成一个毫秒数，只在真弹了确认框时才记，自动放行不计；这个数和追踪层那个 tool.blocked_on_user span 是同一件事的两种呈现。而且决策被写回工具上下文，所以那个 span 结束时能标上准确的批/拒和来源——三层在权限这一点上是打通的。

权限模型本身（ask/allow/deny、分类器、hook 决策）详见第 12 章，这里只关心它怎么被观测。

16.7 一方 / 内部专用的设施：一条诚实的边界 ​

不是所有观测设施都给外部用户。讲清楚哪些你能用、哪些在编译期就被裁掉或只在 Anthropic 内部，才不会误判。

ant-trace 在外部包里是个空壳。它在快照里的实现就一行占位：永远返回“未启用”。这是编译期死代码消除的活标本——外部构建里物理上没有真实现，只留一个永远关着的桩。顺带提醒一句方法论：在公开产物里搜不到某功能的完整逻辑，不等于它不存在，可能只是被编译期裁掉了。

Perfetto 本地追踪也一样，是 Ant-only、编译期门控的。它能把 span 导成 Perfetto UI 里的火焰图，听着很诱人，但源码头就写明“Ant-only”“external build 里被消除”，整个初始化裹在一个编译期特性开关里（perfettoTracing.ts:2、:7、:260）。也就是说，CLAUDE_CODE_PERFETTO_TRACE=1 只在这个特性被编进包时才有用，外部构建里这段已被裁掉，环境变量置了也白置。别把它当成外部用户随手能开的功能。

还有两处只值得一提：去 Anthropic BigQuery 的那条（16.2 讲过，组织 opt-out 门控，外部不经手）；以及一个把终端渲染帧率也纳入自观测的 FPS 追踪——一个 TUI 连自己画得流不流畅都记，是 UX 工程的细致处（渲染器细节见第 14 章）。至于 beta 详细追踪，能把 system prompt、模型输出也写进 span，但有一张严格的可见性表：模型的思考原文是 ant-only，外部用户即使开满也拿不到；system prompt 全文只在这条路径、且每个唯一 hash 只发一次，避免重复上报大文本。

CC 反过来对逆向者埋的那些防御仪器（假工具注入、隐写指纹之类）是另一个话题，本书不展开。

16.8 隐私边界：能看到“形状”，看不到“内容” ​

可观测性和隐私天生拉扯：记得越多越好查，也越危险。CC 的总原则一句话——默认只导出“形状”，内容一律要你显式开。

“形状”指长度、token 数、时长、模型名、工具名、决策类型这类元数据；“内容”指 prompt 原文、模型回复、工具的输入输出、代码和文件。默认走前者，后者得逐项开：

内容开关（env）默认
用户 prompt 原文OTEL_LOG_USER_PROMPTS打码，只留长度
助手回复原文OTEL_LOG_ASSISTANT_RESPONSES脱敏，只留长度
工具参数 / 命令OTEL_LOG_TOOL_DETAILS省略 / 脱敏
工具输入输出OTEL_LOG_TOOL_CONTENT省略
原始 API 请求 / 响应体OTEL_LOG_RAW_API_BODIES不导出
system prompt 全文仅 beta 详细追踪不进普通导出
模型思考原文仅内部外部永不导出

（第 1、3、4 行——用户 prompt / 工具参数命令 / 工具输入输出——在快照里有对应的脱敏代码；第 2 行“助手回复”（OTEL_LOG_ASSISTANT_RESPONSES）与第 5 行 OTEL_LOG_RAW_API_BODIES 同属快照之后新增，据官方文档。）

几条设计意图值得点破。

代码和文件内容永不进指标或事件。官方明说“原始文件内容和代码片段不进 metrics 或 events”，源码侧则用 16.3 那个长名字类型把它变成编译期约束。默认观测面里，你能看到“改了 N 行 TypeScript”，但看不到改了什么。

隐私门控和基数控制常常是同一个旋钮的两面。prompt.id 只进事件、不进指标；app.version 默认关——一个是怕泄可归因信息，一个是怕基数爆炸，但拧的是同一批开关。这不是巧合：往聚合后台少塞信息，既省成本又护隐私，两个诉求经常指向同一个决定。

子进程这块有个容易搞反的点：默认（普通本地会话）CC 把整份环境原样透传给它 spawn 的子进程，OTEL_* 也在内；只有当 claude-code-action 把 CLAUDE_CODE_SUBPROCESS_ENV_SCRUB 置真——也就是会话被暴露给不可信内容的 CI 场景（配了 allowed_non_write_users）——CC 才从子进程环境里剥掉那 4 个携带 Authorization=Bearer 的 OTLP header 变量（OTEL_EXPORTER_OTLP_HEADERS 那一批），免得凭证被 shell 展开外泄给第三方；而后端地址 OTEL_EXPORTER_OTLP_ENDPOINT 任何情况下都不剥离。但据当前官方文档，追踪激活时它会把“这是哪条 trace”的关联信息（W3C 的 TRACEPARENT）注入 Bash/PowerShell 子进程，好让子进程的 span 挂到同一条 trace 上。传的是关联信息，不是导出凭证，两者别混。（这两个环境变量在快照里 grep 不到，属快照之后新增，据官方文档。）

小结 ​

Claude Code 的可观测性不是“打一堆 log”，而是一套分层、按用途裁剪、隐私优先的自省系统。它能正面回答“对一次任务做 EXPLAIN”：一次 prompt 的多个 turn、每 turn 的 API 与工具动作、各自的耗时和消耗、在哪等人、决策来自谁、有没有报错。四层各司其职——事件靠 prompt.id 归拢，追踪靠 span 的父子归属串起，会话记录靠 parentUuid 连边重建因果，指标则一概拒绝这些高基数 id 好保住自己能被聚合。

几条反复出现的设计取舍，值得单独记住：

取舍为什么
四层分开，不塞一个大日志聚合、按条件查、看因果、完整重放是四类问题，各需一种数据结构
聚合层拒绝 prompt.id / 默认不带版本号高基数维度会打爆时序库
指标全用计数器加 delta对丢失、重启、乱序都鲁棒，聚合只做差值
内部 tengu_ 与客户 OTel 双流并行官方产品分析与你自己的可观测互不干扰，从同一处并发
把“等你批权限”单独计时墙钟耗时里“等人”和“执行”混在一起就没法归因
并发请求显式传 span 句柄根治并发追踪的响应错配
弱引用加定时兜底清 span观测设施自己不能变成内存泄漏
会话记录用父子连边、结果指向发起它的调用因果靠显式连边，不靠时间顺序猜
opt-out 两级缓存加熔断观测不能拖垮主流程：可廉价关、容忍陈旧读
默认只导“形状”、内容逐项开用“默认脱敏加显式开启”化解可观测与隐私的张力

版本说明：本章基于 v2.1.88 泄露源码快照做走读，并与官方 Monitoring 文档交叉核对。8 个指标在快照与当前文档间稳定一致；事件清单快照之后大幅扩张，凡超出快照的标识符均标“据官方文档”。/goal、/loop 的追踪细节来自对 2.1.201 客户端的逆向（静态抽取加抓包），单独说明，跟快照里能直接读到的内容分开、不混为一谈。