Claude Code 可观测性怎么做？
#

昨天老冯发了条推特：「做了个 Claude Code Grafana Dashboard，研究下它是怎么做决策、用工具、调 API 花钱的。」结果发现非常多的用户都对这个主题感兴趣。

这是我没想到的，所以今天就来聊一聊 Claude Code 的可观测性。

Claude 的可观测性
#

老冯的想法其实很简单 —— 我想了解 Claude Code 内部工作细节。虽然 Claude Code 不开源（其实被开源过一次），但你可以通过它的监控指标和日志，分析出它的大概工作原理。

Claude Code 提供 OTEL 格式的指标和日志，配置起来也很简单。你只要指定几个环境变量，就可以让它主动推送到支持 OTEL 的监控系统，然后用 Grafana 进行可视化。

# Claude Code OTEL 配置
export CLAUDE_CODE_ENABLE_TELEMETRY=1             # 启用监控
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_LOG_USER_PROMPTS=1                    # 如果要隐藏 Prompt，设置为 0
export OTEL_RESOURCE_ATTRIBUTES="job=claude"      # 添加你自己的标签
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://10.10.10.10:8428/opentelemetry/v1/metrics     # 指标端点，打入 VictoriaMetrics
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://10.10.10.10:9428/insert/opentelemetry/v1/logs    # 日志端点，打入 VictoriaLogs
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative

你可以放在 .bash_profile / /etc/profile.d/claude.sh 或者直接写入 ~/.claude/settings.json 的 env 字段。

难点在于：我去哪找这么一个监控系统和 Grafana 呢？后来我看见这么多人都有需求，就干脆做了一个开箱即用的配置模板。

监控系统
#

你只要找一台 Linux 服务器，运行几行命令把它拉起来，就会自带一个 Claude Code 环境，所有东西都帮你配好了（包括监控）。你也可以直接把自己的 Claude Code 监控接进去。

实际上，如果你已经会用 Claude Code，并不需要了解太多细节。你只要告诉它有这么个东西、能干这么个事，并给它准备一台虚拟机，剩下的事它都能帮你自动搞定。我看有人评论留言就是这么说的，哈哈！

监控事件说明
#

Claude Code 可观测性文档

这个监控面板其实很朴素：上方可以选择会话（Session ID），选择之后，下方会列出各种事件。你可以通过拖动时间轴来查看处理任务过程中产生了哪些事件。

目前最主要的事件分为以下四类：

User Prompt：你对它说了什么，或者给了什么提示词
API Request：调用 API 的请求
Tool Decision：系统决定使用什么工具
Tool Result：工具返回的具体结果

每个事件都有对应的字段。大体上，只要看一眼这个面板，就能明白整个任务的处理流程是怎么回事了。

举个例子，最简单的事件就是 User Prompt，你给 Claude Code 发一条消息，就会产生一个该事件：

User Prompt 事件之后，通常是 API Request，也就是调用 API 模型。这里会有一个 model 字段——Claude Code 区分了快速模型和高质量模型，这里我用的是 GLM-4.7 作为例子，有些简单快速的请求会由 GLM-4.5-air 来处理。

API Request 事件有几个核心字段：Cost 是开销，然后是四个 Token 指标。Token.In/Out 是输入输出的 Token 数，Token Cache Read 则是缓存命中的指标。

API Request 完成之后，通常会有一个 Tool Decision 事件，即模型决定使用什么工具。比如 Bash、Read、Write、Search 等，然后会有一个 Decision Source/Result，表示根据什么标准（配置文件/询问用户/……）选择「批准」或「拒绝」。

Tool Decision 事件之后是 Tool Result 事件。这是调用工具的关键事件，关键字段包括：Tool 的命令、说明、错误、参数、UserID、成功与否等。

其实还有一些其他类型的事件，但最主要的就是上面这四类。更多细节可以参考 Claude Code 的监控文档：https://docs.anthropic.com/en/docs/claude-code/monitoring

沙箱环境
#

当然，老冯也知道「授人以鱼不如授人以渔」，但光说原理没用，干脆直接把东西做好给你算了。所以我做了一个开箱即用的沙箱环境，里面包含了一套完整的 Victoria 监控系统与 Grafana 监控大盘，随便找台 1C2G 的 Linux 虚拟机几分钟就能装好。

这个沙箱除了监控 Claude Code，还可以干很多有趣的事情。最主要的是，它已经替你配置好了常用的 Web Coding 工具：Claude Code、VS Code、Open Code。里面自带 PostgreSQL 和 Nginx，所以如果你需要一个云服务器开发环境，也可以试试。

你也可以在这里直接使用不用翻墙的 GLM 模型，多配置一行参数就好了。关于 Claude Code 最美妙的就是：既然你都已经用它了，那大概也不需要操心这些细节是怎么弄的，直接动嘴让它自己去 Vibe 就好了。

# 切换为其他模型，比如 GLM 4.7
claude_env:
  ANTHROPIC_BASE_URL: https://open.bigmodel.cn/api/anthropic
  ANTHROPIC_API_URL: https://open.bigmodel.cn/api/anthropic
  ANTHROPIC_AUTH_TOKEN: your_api_service_token # 填入你的 KEY！
  ANTHROPIC_MODEL: glm-4.7
  ANTHROPIC_SMALL_FAST_MODEL: glm-4.5-air