12 · 可观测体系

这一章讲一个在架构讨论里几乎从不出现、但决定了产品能不能长期演进的东西：系统怎么知道自己在发生什么。

12.1 埋点密度

先看数字：

12.2 事件命名

所有事件都以 tengu_ 开头（tengu 是内部代号）。从主循环里出现的事件名可以看出命名规律：

命名的两个规律

规律一：成对埋点。xxx_used / xxx_not_used、xxx_before / xxx_after —— 这样才能算出比率和差值，而不只是绝对数。

比如 tengu_streaming_tool_execution_used/not_used 这一对，能直接算出「流式执行器的启用率」。如果某次发布后这个比率突然掉了，说明有代码路径意外地绕过了它。

规律二：带上决策的「为什么」。tengu_auto_mode_decision 不只记录「允许还是拒绝」，还记录 fastPath: 'acceptEdits' | 'allowlist' —— 走的是哪条快速通道。这样才能评估「快速通道挡掉了百分之多少的分类器调用」，也就是这个优化到底值不值。

12.3 查询链路追踪

几乎所有埋点都带两个字段：

queryChainId: queryChainIdForAnalytics,   // 这次用户请求的唯一 ID
queryDepth:   queryTracking.depth,        // 智能体嵌套深度（主 0，子 1，孙 2）

生成逻辑在第 3.9 节讲过：

const queryTracking = toolUseContext.queryTracking
  ? { chainId: toolUseContext.queryTracking.chainId,          // 继承父的链路 ID
      depth:   toolUseContext.queryTracking.depth + 1 }       // 深度 +1
  : { chainId: deps.uuid(), depth: 0 }                        // 顶层，新建

12.4 类型层面的隐私保护

埋点代码里到处是一个奇怪的类型转换：

toolName: sanitizeToolNameForAnalytics(tool.name),
errorDetails: errorContent.slice(0, 2000)
  as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
queryChainId: queryTracking.chainId
  as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,

这个类型的名字直译是：分析元数据_我已确认这不是代码或文件路径。

配套还有清洗函数：sanitizeToolNameForAnalytics() —— 因为 MCP 工具的名字包含服务名，而服务名可能是用户自定义的、含敏感信息的。

12.5 缓存断裂检测

有一个专门的子系统监控提示词缓存的健康度：services/api/promptCacheBreakDetection.ts，由编译期开关 PROMPT_CACHE_BREAK_DETECTION 控制。

它监控什么

正常情况下，一场会话的缓存读取量应该是逐轮递增的（历史越来越长，命中的缓存越来越多）。如果某一轮突然暴跌，说明缓存被打断了 —— 有代码改动了上下文前缀。

但有些下跌是合法的

所以系统提供了主动通知的接口：

// microCompact.ts，缓存编辑执行后
// Notify cache break detection that cache reads will legitimately drop
if (feature('PROMPT_CACHE_BREAK_DETECTION')) {
  notifyCacheDeletion(querySource ?? 'repl_main_thread')
}

// 时间触发的微压缩执行后
// We just changed the prompt content — the next response's cache read will
// be low, but that's us, not a break. Tell the detector to expect a drop.
if (feature('PROMPT_CACHE_BREAK_DETECTION') && querySource) {
  notifyCacheDeletion(querySource)
}

译：我们刚刚改了提示词内容 —— 下一次响应的缓存读取量会很低，但这是我们自己造成的，不是断裂。告诉检测器预期会有一次下跌。

12.6 性能剖析检查点

代码里散布着两套检查点：

// 启动路径
profileCheckpoint('cli_entry')
profileCheckpoint('cli_dump_system_prompt_path')
profileCheckpoint('cli_bridge_path')
...

// 无头模式的延迟追踪
headlessProfilerCheckpoint('before_getSystemPrompt')
headlessProfilerCheckpoint('after_getSystemPrompt')
headlessProfilerCheckpoint('before_skills_plugins')
headlessProfilerCheckpoint('after_skills_plugins')
headlessProfilerCheckpoint('system_message_yielded')
headlessProfilerCheckpoint('query_started')

// 主循环内部
queryCheckpoint('query_fn_entry')
queryCheckpoint('query_snip_start') / queryCheckpoint('query_snip_end')
queryCheckpoint('query_microcompact_start') / ('query_microcompact_end')
queryCheckpoint('query_autocompact_start') / ('query_autocompact_end')
queryCheckpoint('query_setup_start') / ('query_setup_end')
queryCheckpoint('query_api_loop_start')
queryCheckpoint('query_api_streaming_start') / ('query_api_streaming_end')
queryCheckpoint('query_tool_execution_start') / ('query_tool_execution_end')
queryCheckpoint('query_recursive_call')

注意这些检查点的分布：几乎完全对应第 6 章那条五级流水线的每一级。这不是巧合 —— 只有把每一级的耗时单独测出来，才能判断「这一级的优化是不是值得」。

还有一个更重的方案：编译期开关 PERFETTO_TRACING。Perfetto 是 Google 的性能追踪工具，能生成可视化的时间线。

12.7 慢操作日志

编译期开关里有 SLOW_OPERATION_LOGGING，对应的还有一个模块 utils/slowOperations.ts。里面导出了一个函数叫 jsonStringify —— 也就是说，连「把对象转成 JSON 字符串」这个操作都被单独包装并纳入了慢操作监控。

为什么？因为在这个系统里，被序列化的对象可能是几百 MB 的消息历史。JSON.stringify 在这个规模下会阻塞主线程几百毫秒 —— 而主线程同时在渲染流式界面，卡顿会立刻被用户看到。

12.8 内存错误缓冲区

const errorLogWatermark = getInMemoryErrors().at(-1)
...
errors: (() => {
  const all = getInMemoryErrors()
  const start = errorLogWatermark ? all.lastIndexOf(errorLogWatermark) + 1 : 0
  return [ `[ede_diagnostic] ...`, ...all.slice(start).map(_ => _.error) ]
})()

系统在内存里维护一个只保留最近 100 条的环形缓冲区存放错误日志。当一次执行失败时，把「本轮范围内」的错误一起打包进结果。

第 2.7 节讲过这里的水位标记技巧：记住元素的引用而不是数组下标，因为环形缓冲区会移位，下标会滑走。

12.9 内部错误的响亮日志

// To help track down bugs, log loudly for ants
logAntError('Query error', error)

系统区分了两种错误日志：

12.10 埋点的成本意识

最后值得注意的一点：埋点本身也有成本，而 Claude Code 对此有意识。

// query.ts
const dumpPromptsFetch = config.gates.isAnt
  ? createDumpPromptsFetch(toolUseContext.agentId ?? config.sessionId)
  : undefined

注释解释了为什么这个对象只创建一次：