Claude Code SDK #35：Monitoring 全解——OTel metrics × events × traces，把 AI 编程从黑箱变成可观测系统

1. Monitoring 到底在监控什么？

2. 最小可用配置：先让 metrics 和 logs 出来

# 1. 打开 Claude Code telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. 指标：适合进 Prometheus / OTLP collector / 可视化看板
export OTEL_METRICS_EXPORTER=otlp

# 3. 事件：适合排查某次 prompt、tool、API 请求
export OTEL_LOGS_EXPORTER=otlp

# 4. OTLP 目的地
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

claude

3. Metrics：先盯住成本、token 和工具决策

4. Events：用 prompt.id 串起一次任务

1. 先用 api_error 看模型请求有没有失败。这个事件会记录 model、error、status_code、duration_ms、attempt、request_id、speed、query_source、effort 等信息。16
2. 再用 tool_result 看工具是否执行成功。它会记录 tool_name、tool_use_id、success、duration_ms、error_type、输入输出大小，以及权限决策来源等字段。17
3. 最后看 assistant_response 是否真的产出了文本。这个事件只包含模型响应里的文本块，不包含 thinking block 和 tool-use block；它要求 Claude Code v2.1.193 或更高版本。18

5. Traces：只在你需要「调用链」时打开

6. 一个可落地的接入顺序

1. 本机 console 试跑一天：只开 metrics 或 logs 的 console exporter，确认字段和事件量。官方示例支持 console、otlp、prometheus、metrics only、events/logs only 等配置。7
2. 接 OTLP collector：把 OTEL_METRICS_EXPORTER=otlp 和 OTEL_LOGS_EXPORTER=otlp 送到统一 collector，先保留默认导出间隔。quick start 里默认 metrics 为 60000ms、logs 为 5000ms。6
3. 下发团队维度：用 OTEL_RESOURCE_ATTRIBUTES 加 department=engineering,team.id=platform,cost_center=eng-123 这类自定义属性。文档要求它是逗号分隔的 key=value，不能有空格；需要空格时用下划线、camelCase 或 percent-encoding。21
4. 收紧 cardinality：默认先不要打开所有 session 级细分；如果自定义资源字段太多，可以用 OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false 让它们只进 resource block，不进入每条 metric series 的 label。21
5. 只给排障窗口开明文字段：需要查一次事故时，再短期开 OTEL_LOG_TOOL_DETAILS 或相关文本开关；查完关闭。prompt、工具输入、raw API bodies 都不是默认该开的东西。19
6. 最后再上 traces：当 metrics 告诉你「慢」，events 告诉你「哪次失败」，但你还不知道「调用链为什么变成这样」，再打开 tracing beta。4

7. 今天就能做的最小动作

• 在一台测试机上打开 CLAUDE_CODE_ENABLE_TELEMETRY=1，把 metrics exporter 指到 console 或 OTLP collector。6
• 做一张只包含成本、token、活跃时间、编辑工具决策的看板。官方已经导出这些 metrics，足够判断 Claude Code 在团队里是不是失控。2
• 写一条隐私规则：默认不记录 prompt 原文、assistant response、tool input 和 raw API bodies；只有明确排障窗口才开。相关开关在官方变量表里都有列出，且多个内容字段默认关闭。19