claudecode学习第 20 章 · 遥测与可观测性20.1 发现：1710 个遥测事件二进制 strings

目标：讲清 Claude Code 的遥测体系——1710 个 tengu_* 事件、两层分发（be/pe/M/Ne）、本地失败事件存储、事件命名规范与分类、遥测对用户体验的反向作用（/plugin stats、/cost、session 分析）。这是运行时纵深的第三章——从"发生什么"到"怎么知道发生了什么"。受众：专业程序员。本机版本 2.1.220。

20.1 发现：1710 个遥测事件

二进制 strings 中提取的 tengu_* 事件名共 1710 个。Claude Code 几乎在所有操作上都打点。

20.2 两层遥测体系

层级	函数名	含义	目标
Behavior	`be("event_name")`	正常操作发生了	Anthropic 服务器
Problem	`pe("event_name")`	操作失败了	服务器 + 本地磁盘
Metric	`M("event_name", data)`	带结构化数据的指标	服务器
Negative	`Ne("event_name")`	只在对应 flag 开启时上报	调试用途

pe 和 be 的区别：

be("skill_invoke") — skill 被成功调用。正常事件。
pe("skill_invoke_not_found") — skill 没找到。问题事件。

20.3 本地存储

~/.claude/telemetry/
├── 1p_failed_events.<sessionId>.<uuid>.json   ← 发送失败的事件
├── 1p_failed_events.<sessionId>.<uuid>.json
└── ...（33 个文件）

1p_failed_events = 第一方 failed events。正常事件直接上报 Anthropic 服务器。如果发送失败（网络问题、服务端暂时不可用），事件写入本地 JSON 文件，下次启动时重试上报。

文件名包含 sessionId 和随机 uuid——同一次 session 可能产生多个失败批次。

20.4 事件命名规范

所有事件以 tengu_ 为前缀（Claude Code 内部代号）。三段式命名：

tengu_<category>_<detail>

按 category 分类统计

类别	数量	示例
API	~80	`tengu_api_query`、`tengu_api_opus_fallback_triggered`、`tengu_api_slow_first_byte`
Plugin	~45	`tengu_plugin_official_marketplace_fetch`、`tengu_plugin_*`
Session	~48	`tengu_session_search_toggled`、`tengu_session_*`
Agent	~30	`tengu_agent_tool_selected`、`tengu_agent_tool_completed`、`tengu_agent_stop_hook_*`
Skill	~8	`tengu_skill_tool_invocation`、`tengu_skill_invoke_not_found`、`tengu_skill_tool_fork_recursion_blocked`
Hook	~6	`tengu_hook_plugin_metrics`、`tengu_agent_stop_hook_success`
ASM（内部）	~30	`tengu_amber_lattice`、`tengu_amber_flint`、`tengu_alder_compass`

ASM 是什么？ amber_* 和 alder_* 是 ASM（Agent Safety Monitor）的内部事件。这些不是用户可见功能——它们是 Anthropic 内部的安全和监控基础设施。

20.5 事件样例

正常事件（be）

be("skill_invoke")                    ← skill 被成功调用
be("plugin_official_marketplace_fetch") ← 官方 marketplace 拉取成功
be("workflow_discover")               ← workflow 发现完成
be("agent_launcher")                  ← agent 启动

问题事件（pe）

pe("skill_invoke_not_found")          ← skill 名称不存在
pe("skill_invoke_empty_name")         ← skill 调用时传了空名
pe("skill_invoke_model_disabled")     ← skill 被禁止通过模型调用
pe("plugin_official_marketplace_fetch") ← marketplace 拉取失败（重试后）
pe("agent_stop_hook_max_turns")       ← agent hook 达到最大轮次限制

带数据的指标事件（M）

M("tengu_skill_tool_invocation", {
  command_name: "frontend-design",
  execution_context: "inline",
  invocation_trigger: "claude-proactive",
  query_depth: 0,
  ...
})

Skill 每次被调用时上报触发方式（主动/嵌套）、执行环境（inline/fork）、触发深度。这些数据在 /plugin stats 中聚合显示。

20.6 遥测的反向作用

遥测不是单向的"发出去"。它反过来支撑用户可见的功能：

`/plugin stats`

显示每个 skill 的：

过去 7 天的 token 消耗
总调用次数（永不清零）
上次使用时间

这些数据来自 tengu_skill_tool_invocation 事件的本地聚合。

`/cost`

每次 API 调用的 tengu_api_query 事件携带 token 数和模型。/cost 按 session 汇总显示。

Session 分析

tengu_session_* 事件记录会话层面的交互——搜索切换、分支过滤、项目切换。Anthropic 用这些数据优化 CLI 体验。

用户直接感知到的遥测

事件	触发条件	用户体验
`tengu_api_opus_fallback_triggered`	Opus 不可用	"正在 fallback 到备用模型"
`tengu_skill_invoke_not_found`	Skill 名不存在	"Unknown skill: X. Did you mean Y?"
`tengu_agent_stop_hook_blocking`	Stop hook 阻止停止	"Agent hook condition was not met"
`tengu_skill_tool_fork_recursion_blocked`	Fork 递归	被阻止，提示原因

20.7 用户控制

settings.json 中可禁用遥测（Ch06 提到过 API metrics opt-out）。事件种类和上报目标不可自定义——这是最终用户的二进制，不是开发者的 SDK。无法添加自定义事件或更改上报 endpoint。

20.8 本章核心带走

1710 个 tengu_* 事件——每个操作都打点。三段式命名：category_detail。
两层分发：正常事件（be）→ 直接上报；失败事件（pe）→ 写入本地 1p_failed_events.*.json，下次重试。
/plugin stats 和 /cost 的数据源是遥测，不是配置文件。skill 用量和 token 消耗来自事件聚合。
事件名是功能的反向索引。从 tengu_skill_tool_fork_recursion_blocked 可以确认"skill fork 防递归"存在。事件名验证了前 19 章讨论的大部分机制。
用户不可扩展——这是 black-box 遥测，不是 OpenTelemetry。只能开关，不能自定义。

claudecode学习 第 20 章 · 遥测与可观测性