智能体可观测性:看清你的智能体到底在做什么

日志、成本追踪和 OpenTelemetry 支持,能把一个黑箱式的会话变成可追溯的数据——一旦智能体开始自动化运行或在团队中使用,这一点就变得很重要。

为什么观测变得重要

只要你是一个人、以交互方式和智能体一起工作,就能直接看到发生了什么。可一旦智能体开始自动化运行、在团队里使用或跑在 CI/CD 中,你就需要真实的数据:智能体做了什么、花费了多少、调用了哪些工具。

会话日志作为基础数据层

Claude Code 会把每次会话写成 JSONL 文件保存到磁盘上(路径在 ~/.claude/projects/ 下)。这个格式是内部格式,会随版本变化——不要直接解析这些文件,而应该使用 /export 或有文档记录的接口。即使是订阅套餐,/usage 也会直接在终端里显示成本和用量明细。

在终端里追踪成本

/usage 命令会直接在终端里显示当前会话的预估成本和 token 用量,并按 Skills、Subagents、Plugins 以及各个 MCP 服务器分类展示。这个数字是根据 token 计数在本地估算出来的,不是一份权威账单。

用 OpenTelemetry 看全局

在团队或组织层面,Claude Code 原生支持 OpenTelemetry:设置 CLAUDE_CODE_ENABLE_TELEMETRY=1 后,就可以把指标(metrics)、事件(events),以及可选的追踪信息(traces)导出到你自己的可观测性后端(Prometheus、Grafana、Datadog 等等)。这样你就能集中查看所有用户的成本、工具使用情况和安全事件——而不用一台台机器地手动收集日志。

示例

在启动 `claude` 之前执行 `export CLAUDE_CODE_ENABLE_TELEMETRY=1`、`export OTEL_METRICS_EXPORTER=otlp` 和 `export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317`,就足以把指标发送到本地的 OpenTelemetry Collector 环境。

🛠️ 练习——自己动手试试

在本地开启 Claude Code 的成本和会话透明度功能,不需要搭建外部的可观测性技术栈。

在一个正在运行的 Claude Code 会话中执行 /usage,查看按 Skills、Subagents 和 MCP 服务器划分的明细。
打开 /usage,查看成本和用量的明细。
试着设置 CLAUDE_CODE_ENABLE_TELEMETRY=1 和 OTEL_METRICS_EXPORTER=console,重新启动 claude,观察控制台中出现了哪些指标。

✅ 自查清单

☐ 你能否通过 /usage 判断出会话中哪个部分(比如某个特定的 MCP 服务器)消耗的上下文最多?
☐ JSONL 那一行里都记录了什么——这些信息足够让你追溯清楚成本吗?
☐ 在真实的团队环境里,你会选择不启用哪个 OTEL_LOG_* 变量,因为它导出的数据过于敏感?

小测验

在 Claude Code 中,最简单的方式是如何启用 OpenTelemetry 导出的?