Claude Code 过程观测的几种方式

Claude Code 的过程观测有几个层次，从轻量到重型都有，下面分层介绍。

一、交互模式下的即时查看

--debug 标志 — 最直接的方式

启动时加上 --debug 可以看到 API 调用、工具调用、执行耗时等详细信息，输出到 stderr：

1
2
3

claude --debug                          # 完整 debug 输出
claude --debug "api,hooks"              # 只看特定类别
claude --debug-file /tmp/claude-debug.log  # 写入文件，保持终端整洁

--verbose 则是更轻量的开关，可在配置里持久化，或启动时传入。

二、读取本地 JSONL 日志（离线回溯）

Claude Code 的 session transcript 以 JSONL 格式存储在 ~/.claude/projects/ 目录下，里面记录了每次 tool call、thinking step、token 用量等内容。原始文件可读性较差（是 escaped JSON），但可以直接 cat 或用 jq 解析。

社区工具 claude-devtools 可以解析这些文件，它会重建完整的 session transcript —— 每个 tool call 展开、thinking step 可见、token 用量按 turn 分解，subagent 执行以树状结构渲染。

三、通过 Hooks 实时拦截（适合自定义观测）

Hooks 是 Claude Code 的扩展点，可以在 PreToolUse、PostToolUse 等生命周期事件上挂载脚本。这是目前最灵活的方案——你可以在 hook 脚本里把 tool call 的输入/输出写到自己的日志系统，或触发告警。

1
2
3
4
5
6
7
8
9
10
11
12

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "python3 /path/to/logger.py"
      }]
    }]
  }
}

Hook 脚本通过 stdin 收到 JSON 事件，包含 tool 名称、参数、结果等。

四、OpenTelemetry 导出（生产/团队级别）

Claude Code CLI 内置了 OpenTelemetry instrumentation：它会在每次 model request 和 tool execution 上记录 span，发出 token/cost 计数的 metrics，并为 prompt 和 tool result 发出结构化 log event。

开启方式：

1
2
3
4
5

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1   # 开启 Traces（beta）
export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

支持导出到任何接受 OTLP 协议的后端，比如 Honeycomb、Datadog、Grafana、Langfuse，或自托管的 collector。

小结

License

本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。

Share