用 ruflo-observability 的 observe-trace 技能追踪 Agent 执行：Span 收集、Trace 树构建与瓶颈定位实战-港品优选

用 ruflo-observability 的 observe-trace 技能追踪 Agent 执行：Span 收集、Trace 树构建与瓶颈定位实战

【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo

导读

本文讲解 ruflo 仓库中ruflo-observability插件提供的observe-trace技能：如何为一个任务收集分布式追踪 span（span），依据parentSpanId组装出可视化 trace 树，计算每个 span 的耗时与关键路径（critical path），并定位跨 Agent 协作中的性能瓶颈。读完本文，你将掌握一套可复制的 Agent 执行追踪方法论，包括 namespace 路由的正确工具选型、p95 瓶颈判定规则，以及从 Skill 到 CLI 的两套完整操作路径。

一、observe-trace 是什么：为 Agent 任务构建可观测的"执行树"

在多 Agent 协作系统（如 ruflo 的 swarm 编排）中，一次任务会横跨多个 Agent：architect 设计、coder 写文件、tester 跑测试，每个动作又包含若干子操作。observe-trace技能的核心目标，就是把这些散落在各处的执行片段——span——按父子关系收集起来，组装成一棵完整的 trace 树，回答三个问题：

执行了什么：哪些 span 真正运行了，归属哪个 Agent；
耗时多久：每个 span 的endTime - startTime是多少，整条链路的瓶颈在哪；
如何协作：Agent 之间以什么顺序、什么依赖关系完成了任务。

该技能定义于 observe-trace/SKILL.md，其 frontmatter 明确了调用契约：

name: observe-trace description: Trace agent execution by collecting spans and building a trace tree for a task argument-hint: "<task-id>" allowed-tools: mcp__plugin_ruflo-core_ruflo__memory_search mcp__plugin_ruflo-core_ruflo__memory_list mcp__plugin_ruflo-core_ruflo__agentdb_semantic-route mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize mcp__plugin_ruflo-core_ruflo__agentdb_pattern-search Bash

它属于ruflo-observability插件（结构化日志 + 分布式追踪 + 指标采集），安装方式为：

claude --plugin-dir plugins/ruflo-observability

插件默认按description自动触发 Skill（progressive disclosure），因此当任务描述涉及"追踪执行流程、分析跨 Agent 耗时"时，observe-trace会被自动调用，入参即为<task-id>。

二、六步工作流：从原始 span 到可视化 trace 树

observe-trace的核心是六步流水线，每一步都有明确产出：

1. 收集 spans——用`memory_`而非`agentdb_hierarchical-`

第一步调用mcp__plugin_ruflo-core_ruflo__memory_search --namespace observability（或用memory_list），按<task-id>检索全部 span。这是全流程中最容易踩坑的一步，关键在于工具族的选择：

memory_*工具族按 namespace 路由，传--namespace observability即可精确取回该命名空间下的 span；
agentdb_hierarchical-*工具族按 tier 路由（working | episodic | semantic），忽略 namespace 字符串——如果沿用旧写法传 namespace 参数，读取会静默失败。

这条路由规则来自 ruflo-agentdb ADR-0001 §"Namespace convention"，是插件体系内反复出现的一类 bug：ruflo-observability早期版本的技能曾用agentdb_hierarchical-recall携带observabilitynamespace 参数，结果被静默忽略。ADR-0001（0001-observability-contract.md）已将该修复固化为契约，并在 smoke 脚本中专门校验"技能必须使用memory_*而非hierarchical-*+ namespace"。

2. 构建 trace 树——按`parentSpanId`组装父子层级

拿到全部 span 后，用每条 span 的parentSpanId字段建立父子引用：根 span（root）的parentSpanId为 null，位于树顶；其余 span 挂到对应父 span 之下。产物形如：

[root] swarm-task [child] agent-spawn (agent=architect) [child] agent-spawn (agent=coder) [child] file-read (path=src/auth.ts) [child] file-write (path=src/auth.ts) [child] agent-spawn (agent=tester) [child] test-run (suite=auth)

3. 计算时序——duration 与关键路径

对每个 span 计算duration = endTime - startTime，随后识别关键路径（critical path）——串行 span 链中耗时最长的那条链。关键路径决定了整个任务的端到端下限：优化关键路径上的 span，收益直接反映到总耗时；而并行分支上的耗时则不影响整体。

4. 识别瓶颈——p95 基准与空闲间隙

两步判定：

超时判定：某 span 的 duration 超过该操作类型的p95 分位数，即标记为瓶颈（如swarm_span_duration_ms直方图的 p95）；
空闲判定：span 之间的间隙（gap）过大，暗示存在等待、轮询或调度延迟，同样视为瓶颈信号。

p95 基准来自同 namespace 下历史度量数据的聚合（详见下文observe-metrics的基线逻辑），因此这一判定是统计意义上的，而非拍脑袋的固定阈值。

5. 综合——用`agentdb_context-synthesize`生成叙事

调用mcp__plugin_ruflo-core_ruflo__agentdb_context-synthesize，把 span 元数据合并成一段自然语言的执行流摘要。该工具的底层实现位于 agentdb-tools.ts：接受query与可选maxEntries（默认 10，上限受MAX_TOP_K约束），将命中的记忆条目综合为紧凑上下文——其设计初衷正是"为 LLM 调用生成紧凑检索上下文"，与本步骤的叙事化目标一致。

6. 报告——结构化输出 trace 树

最终报告必须包含，每行一个 span：

span name（操作名）
agent（归属 Agent）
duration（耗时）
status（OK / ERROR）
bottleneck flag（是否瓶颈）

并额外给出总 trace 耗时与关键路径耗时两项汇总指标，方便一眼定位问题。

三、CLI 替代方案：不开对话也能追 trace

技能是面向 Agent 对话的入口；若要在终端直接操作，等价命令为：

npx @claude-flow/cli@latest memory search --query "trace spans for task TASK_ID" --namespace observability

注意两点前提：

CLI 版本按ruflo-observability的兼容性约定，固定在@claude-flow/cliv3.6 的 major+minor 上（见 README.md 的 Compatibility 段）；
该命令等价于技能第一步"收集 spans"，后续建树、算时序、定瓶颈仍需按上述流程处理。

此外，observability-engineer 还提供了memory store写入路径，便于在任务完成后回填追踪摘要：

npx @claude-flow/cli@latest memory store --namespace observability --key "trace-TRACE_ID" --value "TRACE_SUMMARY_JSON"

四、底层原理：OpenTelemetry 兼容的 span 数据模型

observe-trace操作的 span 遵循 OpenTelemetry 兼容模型，字段定义见 observability-engineer.md：

字段	说明
`traceId`	整个请求流的唯一 ID
`spanId`	本操作的唯一 ID
`parentSpanId`	父 span 的 ID（根 span 为 null）
`operationName`	人类可读的操作名
`startTime`/`endTime`	span 起止时间
`status`	OK、ERROR 或 TIMEOUT
`attributes`	键值元数据（agent、task、model 等）

这些 span 与结构化日志共用同一套关联字段（correlationId、agentId、taskId、spanId、traceId、duration_ms），JSON 日志格式即：

{ "timestamp": "2026-04-29T12:00:00.000Z", "level": "info", "message": "Request processed", "correlationId": "corr-abc123", "agentId": "coder-01", "taskId": "task-xyz", "spanId": "span-456", "traceId": "trace-789", "duration_ms": 42, "metadata": {} }

正是这套统一字段，让 trace 树、日志流和指标快照可以按taskId/correlationId自由交叉关联。

五、与 observe 命令家族的协同：不止于 trace

observe-trace技能对应的显式命令入口是/observe（observe.md），共 5 个子命令，trace 只是其一：

observe trace <task-id> # Trace agent execution with span tree observe metrics [--period 1h] # View aggregated metrics (p50, p95, p99) observe logs [--level error] # Filter structured logs by level observe dashboard # Combined health dashboard observe correlate <agent-id> # Correlate all telemetry for an agent

其中与 trace 强相关的是：

observe metrics：为第 4 步的 p95 基准提供数据来源。它从observabilitynamespace 取度量，聚合 counter（求和）、gauge（当前值）、histogram（p50/p95/p99），并用agentdb_pattern-search（ReasoningBank 路由，切勿传 namespace 参数）建立基线，偏差超过 2 个标准差即标记为异常；
observe correlate <agent-id>：把某 Agent 的日志、trace、指标按时间线合并，呈现 spawn、任务指派、完成、出错的全过程——相当于把多棵 trace 树按 Agent 维度重投影。

observe-trace技能也允许在步骤中调用agentdb_pattern-search与agentdb_semantic-route：前者用于比对历史异常模式，后者用于对 trace 查询做意图路由。

六、验证契约：smoke 脚本如何守住这条追踪链路

ruflo-observability以 smoke.sh 作为契约，运行方式：

bash plugins/ruflo-observability/scripts/smoke.sh # Expected: "10 passed, 0 failed"

10 项检查中与本技能直接相关的是第 2、3、10 项：

第 2 项：校验observe-trace/observe-metrics两个 SKILL.md 的 frontmatter 存在name:、description:、allowed-tools:，且 agent 与 command 文件齐全；
第 3 项：正向断言 observe-trace 使用了memory_search或memory_list，反向断言其不再出现agentdb_hierarchical-recall+observability的组合——这正是 ADR-0001 修复的 namespace 路由 bug 的回归防线；
第 10 项：禁止任何技能使用allowed-tools: *通配授权，保证 trace 检索只经由白名单工具。

这意味着：如果你改动 observe-trace 的检索路径，smoke 第 3 项会直接拦截，确保 namespace 路由约定不被回退。

七、使用建议与注意事项

始终用memory_*做 namespace 读取：observability是ruflo-observability插件持有的专属 namespace（基础名例外，与federation、migrations同先例），且该命名空间禁止与保留 namespace（pattern、claude-memories、default）冲突。任何agentdb_hierarchical-*传入 namespace 的写法都是历史 bug，应避免；
瓶颈判定要有基线：p95 是统计量，首次接入、历史数据不足时，第 4 步应先用observe metrics预热基线，否则 p95 判定可能失真；
关键路径优先：排查性能问题时，先看关键路径上的 span 与 span 间隙，并行分支的优化优先级靠后；
trace 数据要回填：利用memory store --namespace observability把 trace 摘要沉淀为可检索的记忆，后续同类任务可直接用memory search命中历史模式。

企业官网建设流程全解析