分布式链路分析 Skill：沿 Trace 定位跨服务性能瓶颈

5 分钟阅读 PolyForm Noncommercial 1.0.0

AI 测试Agent Skills分布式链路分析

分布式请求跨过多个服务后，单一日志很难解释延迟来自哪里。Trace 的价值不在瀑布图本身，而在于它能还原一次用户请求的因果路径。

分布式追踪分析 Skill 将 span、传播关系和耗时读成端到端故事，定位延迟或故障被引入的位置。

本文通过具体场景说明如何收集、连接和解释证据，让结论能够服务下一步的工程或业务决定。

分布式链路分析 Skill 用来做什么

分布式链路分析适合需要解释跨服务慢请求和错误传播的研发、SRE 与 QA 团队。它把 Trace、指标和日志放到同一时间窗口，减少“最长 Span 就是根因”的误判。

先回到源 Skill

这个 Skill 的完整执行规则在 分布式链路分析 提示词。源目录还包含 3 个评测用例，用于验证输出是否遵守契约。

它要求特别注意：

  • 相关性不等于根因
  • 标明采样和时钟偏差
  • 同时检查总耗时、重试、排队和下游等待

用一份项目材料开始

先把当前拿得到的材料摆上来。缺口可以保留，状态必须说实话。

材料这次填什么缺失时的处理
目标与范围用一次结账失败的 trace 定位跨网关、订单、支付和通知服务的耗时与错误传播标出不在本轮判断内的链路
版本与环境trace ID、采样率、请求时间、服务版本和区域trace 不完整时只描述可见 span
证据span 时间、父子关系、服务日志、指标和请求样本缺少关联 ID 时标注定位盲区
决策边界根服务候选、下钻顺序、采样补充和通知 Owner不把最慢 span 直接写成根因

可以这样调用：

请使用 distributed-trace-analysis Skill。

任务：用一次结账失败的 trace 定位跨网关、订单、支付和通知服务的耗时与错误传播
输入材料：[版本、链接、日志或报告路径]
范围：[本次包含和排除的对象]
限制：[时间、数据、权限、合规要求]

先审计输入，再按风险和证据强度排序。材料没有证明的内容标为假设，并列出验证方法。

分布式链路分析要交付一条可复核的因果链

产物要回答的问题最低证据
Trace 上下文请求从哪里进入，经过哪些服务trace ID、时间窗口和采样率
Span 时序等待、重试和执行时间分别是多少span duration、queue time 和事件
错误传播哪个服务首次返回错误，影响怎样扩散status、错误类型和下游响应
候选瓶颈哪项证据支持根因假设对照 Trace、指标和日志的验证动作

没有完整 Trace 或统一时间窗口时，只能提出定位假设，不能把最长 Span 当成根因。

在项目里跑一轮

先用一个边界清楚的小回合启动——用一次结账失败的 trace 定位跨网关、订单、支付和通知服务的耗时与错误传播。别急着把结果写成报告。先把输入版本、时间窗口和负责人贴到同一处；然后把每个判断连回具体材料；最后只安排一项能改变结论的验证动作。

先确认 trace 完整性和时间对齐，再判断哪个 span 是原因、哪个只是后果。这一轮交付应当包含：可复查的证据索引、仍然成立的假设、以及下一位同事可以直接执行的动作。这样做很朴素，也很有效。

进阶使用：把一次分析变成持续机制

先确认 trace 完整性和时间对齐，再判断哪个 span 是原因、哪个只是后果。

每次分布式链路分析都保存 Trace ID、采样配置、部署版本和时间窗口。服务拓扑或采样策略变化时，重新对齐受影响链路，避免把不同版本的 Span 混在一起。

三段式 Skill 链

metrics-anomaly-analysis → distributed-trace-analysis → root-cause-analysis

交接传递内容接收方要检查什么
上游到 distributed-trace-analysis来源版本、范围、风险、未决项输入是否过期，冲突是否标记
distributed-trace-analysis 到下游判断、证据索引、残余风险、待办产物是否可执行，Owner 是否明确
下游回写 distributed-trace-analysis执行结果、缺陷、事实变化是否更新基线与回归范围

交接时传摘要、证据索引和原始材料的位置。信息量足够，结论出了问题也能回到来源。

团队门禁

门禁检查内容未满足时
distributed-trace-analysis 输入门禁版本、环境、证据来源和 Owner停止生成，列出缺口
distributed-trace-analysis 产物门禁关键结论带依据、状态和影响退回补证据
distributed-trace-analysis 执行门禁命令、查询或验证路径可复现标记基础设施或测试问题
distributed-trace-analysis 决策门禁残余风险有接受人与日期不进入下一阶段

容易踩的坑

  1. 只看总耗时，漏掉排队、重试和下游等待。
  2. 把采样不完整的 Trace 当作全链路事实。
  3. 没有对齐部署版本和时间窗口，就比较不同请求。
  4. 看到最长 Span 就直接归责，未用指标和日志验证。

相关 Skill

Trace 只能说明链路上的事实，根因和时间窗口还需要其他证据：

交付前复核：把判断落到证据

Skill 输出拿到手后，先核对四件事：输入版本是否明确，范围是否完整，每条结论能否回到证据，下一步由谁执行。少一项，报告就容易变成漂亮的猜测。

项目需要留下缺失时
输入边界版本、环境、时间窗口和本次范围标记假设，不写成事实
证据索引日志、报告、Trace、截图或命令输出标记 evidence_pending
结论状态verified、assumption、blocked 或 pending停止扩大结论
后续动作最小验证命令、负责人和截止时间交付为待办，不进入门禁
source_version: [版本或提交]
scope: [本次包含和排除的对象]
evidence: [日志、报告、Trace 或命令输出]
status: pending
owner: [负责人]
next_action: [最小验证动作]

分析类 Skill 要保留查询条件和时间窗口；执行类 Skill 要保留命令、退出码和失败产物。人工修改也要记录，下一次复核才知道结论从哪里变化。

安装与调用

安装这个 Skill：

npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh/testing-types/distributed-trace-analysis -g

安装后，直接使用下文的 distributed-trace-analysis 调用词，并附上本次的真实材料。

常见问题

输入还不完整，能开始吗？

能。先交付受限初版：列出已知事实、假设、缺口和最小验证动作。环境、数据或权限缺失时，不写执行结论。

什么时候需要人工确认？

范围取舍、风险接受、生产操作、数据权限和发布决定必须由对应负责人确认。Skill 负责整理证据与选项，不替团队做授权决定。

先用一份真实材料跑通 分布式链路分析，把输入、产物、人工修改和验证证据留在同一个工作链里。下一次变化发生时，才有东西可以复用。

参考

安全测试白盒测试背靠背测试本地化测试边界测试
分享