用 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技能如何为一个任务收集分布式追踪 spanspan依据parentSpanId组装出可视化 trace 树计算每个 span 的耗时与关键路径critical path并定位跨 Agent 协作中的性能瓶颈。读完本文你将掌握一套可复制的 Agent 执行追踪方法论包括 namespace 路由的正确工具选型、p95 瓶颈判定规则以及从 Skill 到 CLI 的两套完整操作路径。一、observe-trace 是什么为 Agent 任务构建可观测的执行树在多 Agent 协作系统如 ruflo 的 swarm 编排中一次任务会横跨多个 Agentarchitect 设计、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自动触发 Skillprogressive 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即可精确取回该命名空间下的 spanagentdb_hierarchical-*工具族按 tier 路由working | episodic | semantic忽略 namespace 字符串——如果沿用旧写法传 namespace 参数读取会静默失败。这条路由规则来自 ruflo-agentdb ADR-0001 §Namespace convention是插件体系内反复出现的一类 bugruflo-observability早期版本的技能曾用agentdb_hierarchical-recall携带observabilitynamespace 参数结果被静默忽略。ADR-00010001-observability-contract.md已将该修复固化为契约并在 smoke 脚本中专门校验技能必须使用memory_*而非hierarchical-* namespace。2. 构建 trace 树——按parentSpanId组装父子层级拿到全部 span 后用每条 span 的parentSpanId字段建立父子引用根 spanroot的parentSpanId为 null位于树顶其余 span 挂到对应父 span 之下。产物形如[root] swarm-task [child] agent-spawn (agentarchitect) [child] agent-spawn (agentcoder) [child] file-read (pathsrc/auth.ts) [child] file-write (pathsrc/auth.ts) [child] agent-spawn (agenttester) [child] test-run (suiteauth)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 树最终报告必须包含每行一个 spanspan name操作名agent归属 Agentduration耗时statusOK / ERRORbottleneck flag是否瓶颈并额外给出总 trace 耗时与关键路径耗时两项汇总指标方便一眼定位问题。三、CLI 替代方案不开对话也能追 trace技能是面向 Agent 对话的入口若要在终端直接操作等价命令为npx claude-flow/clilatest memory search --query trace spans for task TASK_ID --namespace observability注意两点前提CLI 版本按ruflo-observability的兼容性约定固定在claude-flow/cliv3.6 的 majorminor 上见 README.md 的 Compatibility 段该命令等价于技能第一步收集 spans后续建树、算时序、定瓶颈仍需按上述流程处理。此外observability-engineer 还提供了memory store写入路径便于在任务完成后回填追踪摘要npx claude-flow/clilatest memory store --namespace observability --key trace-TRACE_ID --value TRACE_SUMMARY_JSON四、底层原理OpenTelemetry 兼容的 span 数据模型observe-trace操作的 span 遵循 OpenTelemetry 兼容模型字段定义见 observability-engineer.md字段说明traceId整个请求流的唯一 IDspanId本操作的唯一 IDparentSpanId父 span 的 ID根 span 为 nulloperationName人类可读的操作名startTime/endTimespan 起止时间statusOK、ERROR 或 TIMEOUTattributes键值元数据agent、task、model 等这些 span 与结构化日志共用同一套关联字段correlationId、agentId、taskId、spanId、traceId、duration_msJSON 日志格式即{ 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 命令家族的协同不止于 traceobserve-trace技能对应的显式命令入口是/observeobserve.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当前值、histogramp50/p95/p99并用agentdb_pattern-searchReasoningBank 路由切勿传 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 failed10 项检查中与本技能直接相关的是第 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-recallobservability的组合——这正是 ADR-0001 修复的 namespace 路由 bug 的回归防线第 10 项禁止任何技能使用allowed-tools: *通配授权保证 trace 检索只经由白名单工具。这意味着如果你改动 observe-trace 的检索路径smoke 第 3 项会直接拦截确保 namespace 路由约定不被回退。七、使用建议与注意事项始终用memory_*做 namespace 读取observability是ruflo-observability插件持有的专属 namespace基础名例外与federation、migrations同先例且该命名空间禁止与保留 namespacepattern、claude-memories、default冲突。任何agentdb_hierarchical-*传入 namespace 的写法都是历史 bug应避免瓶颈判定要有基线p95 是统计量首次接入、历史数据不足时第 4 步应先用observe metrics预热基线否则 p95 判定可能失真关键路径优先排查性能问题时先看关键路径上的 span 与 span 间隙并行分支的优化优先级靠后trace 数据要回填利用memory store --namespace observability把 trace 摘要沉淀为可检索的记忆后续同类任务可直接用memory search命中历史模式。相关资源技能定义observe-trace/SKILL.md插件总览与指标清单ruflo-observability/README.md命令手册commands/observe.md追踪与日志字段模型agents/observability-engineer.md契约 ADRdocs/adrs/0001-observability-contract.mdnamespace 约定ruflo-agentdb/docs/adrs/0001-agentdb-optimization.mdagentdb_context-synthesize实现agentdb-tools.ts【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考