如何观测 AI 智能体的每一步行为?Rome 的 OTEL → ClickHouse → HyperDX 追踪管线详解
如何观测 AI 智能体的每一步行为?Rome 的 OTEL → ClickHouse → HyperDX 追踪管线详解
想让 AI 智能体的每一次工具调用、每一轮模型对话都有迹可循?开源项目 Rome(一个面向递归智能体的操作系统)内置了一条完整的 AI 智能体追踪管线:基于 OpenTelemetry(OTEL)采集 Spans、Logs、Metrics 三类信号,经 OTEL Collector 转发到 ClickHouse 存储,最终在 HyperDX 中以仪表盘呈现。本文将带你完整看懂这条管线的架构、设计原则与查看方式,无需深厚背景也能上手。
为什么 AI 智能体行为需要"可观测"?
传统应用出问题,看一行报错日志往往就够了。但 AI 智能体(Agent)的行为链长得多:
收到用户消息 → 触发 hook → 智能体开始一轮推理 → 调用模型 → 执行工具/动作 → 可能召唤子智能体 → 回复
任何一个环节变慢或失败(比如"召唤子智能体为什么花了 20 秒?"),光看结果消息根本无法定位。Rome 的解法是:把智能体的每一步都变成一条带时间戳、可关联、可查询的遥测记录,让"这一步谁做的、花了多久、花了多少 token"成为一条 SQL 就能回答的问题。
管线全貌:OTEL → Collector → ClickHouse → HyperDX
整条管线只有一条核心链路(详见 docs/architecture/observability.md):
Rome 实例 ──OTLP──► OTEL Collector ──► ClickHouse ──► 消费者(HyperDX 仪表盘 / SQL 查询)
各环节分工:
| 环节 | 角色 | 说明 |
|---|---|---|
| Rome 实例 | 信号发射端 | 内置 packages/core/src/telemetry.ts 初始化 OTEL SDK,通过 OTLP 协议(HTTP :4318 / gRPC :4317)上报 |
| OTEL Collector | 中转与缓冲 | 独立容器,配置见 infra/observability/otel-collector-config.yaml,带内存保护(memory_limiter)与批量发送(batch),失败自动重试 |
| ClickHouse | 统一存储 | 所有实例写入同一批 otel_* 表,按 service.instance.id 逻辑隔离 |
| HyperDX | 人类界面 | 仪表盘与搜索界面,开发环境地址为 http://obs.rome.localhost:3000 |
开发环境与生产环境跑的是同一份 Collector 配置,唯一的差别是 ClickHouse 目标地址。开发机的 rome-obs 单例栈(infra/observability/compose.yml)还内置了一个 HyperDX 本地捆绑包,方便断网时使用。
三类信号:Spans、Logs、Metrics
Rome 上报 OTEL 标准的三类信号,完整字段清单见 docs/observability/schema.md:
🕐 Spans(追踪跨度)——回答"发生了什么、花多久"
每个 Span 都带有 session.id(所属会话)、service.instance.id(所属实例)等属性。智能体链路上的每一类行为都有约定俗成的 Span 命名:
| Span 名 | 含义 | 发出者 |
|---|---|---|
channel:{name}.handle |
收到某频道的一条入站消息 | 频道入口 |
hook:{name} |
一次 hook 触发 | Hook 注册表 |
agent:{name} |
智能体的一轮推理 | AgentRunner |
model.turn / model.call |
一次模型调用(带 token、成本、stop_reason) | 模型提供方 |
action:{name} |
一次工具/动作执行 | 动作注册表 |
summon:{child} |
召唤一个子智能体 | Subagent 动作 |
一次入站消息的 Span 层级形如一棵树(golden-trace 集成测试 正是用来固化这棵树形状的):
channel:telegram.handle
└── hook:channel-message
└── agent:main
├── model.turn
└── action:demo_action
其中 model.turn Span 会在回合结束时被打上 input_tokens、output_tokens、estimated_cost_usd、stop_reason 等计费属性(见 packages/core/src/core/agent-session.ts#L3447)——一个会话花了多少钱,一条聚合 SQL 就能算出来。
📝 Logs(日志)——回答"细节是什么"
createLogger(component) 打出的每条日志同时写容器 stdout(docker logs | jq 照常可用)和 ClickHouse 的 otel_logs 表。在 Span 内发出的日志会自动关联 TraceId / SpanId,于是"看日志"和"看追踪"是同一份数据。
📈 Metrics(指标)——回答"趋势如何"
所有指标统一以 rome_ 为前缀,例如:
rome_model_tokens_total:token 用量计数器(按模型、方向、会话分组)rome_action_duration_ms:动作耗时直方图rome_session_duration_ms:会话总耗时
Collector 侧还有精细的分阶段耗时指标(见 packages/core/src/telemetry.ts#L377-L408),专门用于拆解"召唤子智能体为何慢":worker 冷启动、会话获取、CLI 子进程启动、首 token 延迟(TTFT)……
四条设计原则:这条管线为什么这样建?
Rome 在 架构文档 中明确了几条不变式(Invariants),理解它们才算真正看懂管线:
- 逻辑隔离,而非物理隔离。 所有实例写同一批 ClickHouse 表,
service.instance.id是遥测隔离边界。应用侧的查询助手会自动注入该过滤条件,防止代码"误读"别的实例的数据。 - Rome 永不阻塞在观测栈上。 OTLP 上报是 fire-and-forget,导出失败不算事故——观测栈挂掉绝不能影响智能体本身干活。
- ClickHouse 凭据只存在于 Collector。 Rome 容器只知道"把 OTLP 发到旁边的 Collector",存储目标可随意替换(HyperDX 本地、ClickStack Cloud、自托管),且 Rome 进程被攻破也不会泄露中央存储的写权限。
- Collector 启动即校验(fail-closed)。 启动时会实际创建 OTEL 表来验证目标;凭据缺失或不可达,容器直接 crash-loop,而不是静默丢数据。
仪表盘即代码:pnpm obs:dashboards
Rome 没有手点鼠标拼仪表盘,而是把仪表盘定义成代码,用 ClickHouse Cloud OpenAPI 幂等下发。预置的智能体追踪仪表盘(infra/observability/dashboards/agent-traces.mjs)包括三块:
- Agent · Conversation Trace:按
session.id圈定一次对话,查看 span 数量、回合数、错误数,以及按时间排列的完整时间线; - Agent · Actions, Hooks & Routines:动作/hook 的调用量、真实失败率(错误数/总数)、p95 最慢榜单;
- Agent · Errors & Slow Traces:按组件分组的错误日志趋势、最近错误日志、最慢 Span 下钻列表。
应用方式只有一条命令(需先配置 ClickHouse Cloud API 密钥):
pnpm obs:dashboards
新增仪表盘只需在 infra/observability/dashboards/ 下加一个模块并注册到 apply 列表,详见该目录的 README。
动手查看:两个最常用的查询姿势
图形界面(推荐新手):打开 HyperDX UI(开发环境 $OBS_UI_URL),在搜索表单上按 service.instance.id 过滤到自己的实例,即可浏览 Span 瀑布图与日志。
直接写 SQL:把 SQL POST 到 ClickHouse 查询端点即可。两个最实用的示例(完整版见 docs/observability/schema.md):
-- 某会话里最耗时的 20 个 span
SELECT SpanName, Duration, SpanAttributes
FROM default.otel_traces
WHERE ResourceAttributes['service.instance.id'] = '$PANTHEON_SLUG'
AND SpanAttributes['session.id'] = 'sess-abc'
ORDER BY Duration DESC
LIMIT 20
-- 某会话的模型成本汇总(按模型分组)
SELECT SpanAttributes['model.id'] AS model,
sum(toFloat64OrZero(SpanAttributes['model.cost_usd'])) AS cost_usd
FROM default.otel_traces
WHERE ResourceAttributes['service.instance.id'] = '$PANTHEON_SLUG'
AND SpanAttributes['session.id'] = 'sess-abc'
AND SpanName = 'model.call'
GROUP BY model
小结
Rome 的观测方案给所有做 AI 智能体系统的人提了一个可借鉴的样板:
- 用 OTEL 标准协议做采集,不造私有心跳协议;
- 用约定命名(
agent:*、action:*、model.turn)把智能体行为链固化成可查询的 Span 树; - 用 ClickHouse 单存储统一承载 traces/logs/metrics,逻辑隔离代替物理隔离;
- 用 HyperDX 给人看、用 raw SQL 给代码查,两种姿势读同一份数据;
- 关键不变式:观测永不反噬业务,且存储凭据与业务进程严格分离。
如果你正在为一个递归智能体系统设计"黑匣子",不妨对照 docs/observability/schema.md 与 infra/observability/ 下的配置,这条管线可以直接抄作业。

