Tracely 失败聚类深度指南：从 31 条失败 Trace 到 1 个可追踪的故障 Issue-平芜编程栈

【免费下载链接】Tracely-ai

Trace-native CI/CD for AI agents: grade production traces, cluster failures, freeze them into replayable regression tests, and block PRs that regress. Self-hostable.

项目地址：https://gitcode.com/gh_mirrors/tr/Tracely-ai

点击查看免费下载

Tracely 是一款 Trace 原生的 AI Agent 可观测性与 CI/CD 工具。它的**失败聚类（Failure Clustering）**能力，可以把生产环境中同因失败的 31 条 Trace 自动收敛成 1 个可追踪的故障 Issue：自动归组、LLM 根因分析、版本归因，还能一键把 Issue 冻结成可重放的回归测试，从源头拦住下一次回归。

为什么逐条看 Trace 定位不了 AI Agent 故障 🤔

一次部署之后，Trace 列表里躺着 31 条失败记录。逐条打开，你会发现它们其实死在同一个错误上——ValueError、工具超时、鉴权失败……但问题在于：

错误消息里的ID、订单号、时间戳各不相同，两条同因失败看起来完全是"两条不同的报错"；
31 次失败可能来自200+ 次调用中的不同请求，人眼无法快速确认"它们是不是同一类问题"；
就算确认了，你还得回答：什么时候开始出现的？哪个版本引入的？该修什么？

Tracely 的失败聚类把"按失败种类分诊"变成了自动流程：同因失败的 Trace 自动归入同一个Failure cluster（失败簇），每个簇就是一个带计数、时间线、版本归因与修复建议的故障 issue，而不是 31 个待办。

失败聚类如何工作：两阶段机制 🔍

第一阶段：摄入时的结构签名（秒级归组，零模型成本）

一条 Trace 一旦被评估器判为失败，Tracely 立刻计算它的结构签名（signature）：

取出失败的评估器集合+错误文本；
掩码掉易变部分：UUID/十六进制 ID →<id>、数字 →<n>、引号字符串 →<*>，再压缩空白；
取sha256 前 16 位作为稳定的 cluster key。

于是，两条 Trace 抛出了同一个异常——哪怕消息里的订单号完全不同——也会在几秒内落入同一个簇，全程不需要任何模型调用。签名里还内置了防碎片规则：掩码后文本几乎一致（token 重叠度 ≥ 0.9）就判定为同一 issue 合并；只有失败的评估器集合完全不同，才会把措辞相似的失败保留成两个簇。这套签名逻辑实现在 signature.py。

第二阶段：按需语义聚类（Analyze failures 按钮）

结构签名只能合并"长得一样"的失败。点一下页面上的⚡ Analyalyze failures，Tracely 会做一次完整的语义重建：

每条失败 Trace 被描述成机制性文本——问了什么、哪个工具坏了、答案哪里跑偏；
文本转成embedding 向量，用HDBSCAN做密度聚类；
数据量大时先UMAP 降维再聚类，小数据集则直接按余弦距离聚类，避免高维空间里出现"幽灵簇"；
一个 LLM 分析师为每个簇写出 issue：标题、机制分析（Analysis）、修复建议（Proposed fix），甚至给出一个能继续拦住这类失败的建议评估器（Suggested evaluator）；
再来一轮合并与拆分：真正是一个问题的 issue 合并，藏着一个簇里的两个问题拆开。上一轮的 Promote / Ignore 状态会自动继承，不会让你重复确认。

聚类引擎的算法选择逻辑见 clustering.py，完整流水线（embedding → 聚类 → LLM 分析 → issue 整合）在 failure_intel_service.py。

💡 第二阶段依赖工作区的OpenRouter key（embedding + LLM 分析都走它）；没有配置时按钮置灰，你依然保留第一阶段的结构性簇。

一个 Issue 长什么样：从计数到版本归因 🎯

看一个真实形态的例子：13 条 Trace 抛出了同样的ValueError: kaboom，全部被收进一个 cluster。点进去，每个区块都在回答一个分诊问题：

区块	回答的问题
Occurrences	它何时发生？尖峰 = 某次部署引入的；平线 = 一直如此的老毛病
By agent version	哪个版本引入的？见下方"版本归因"规则
Analysis / Proposed fix	机制是什么、该改什么——LLM 写好的成文分析
Suggested evaluator	一条能继续拦住这类失败的草稿评估器，点Create evaluator直接预填创建表单
Signature	那个掩码后的结构指纹，可复制到检索/告警里用
Member traces	簇里每一条 Trace，标出REPRESENTATIVE代表样本，点击直达详情

版本归因（introduced in）的判定很克制：只有当更早的版本已经服务过足够多的干净运行（默认 20 条以上）且一条都没落进这个簇时，第一个出问题的版本才会被点名——"v2 跑了 340 次零失败，v3 跑出 41 次失败"，于是结论是introduced in v3。从第一个版本就存在的失败，永远不会被冤枉到某一个版本头上（规则实现见 versions.py）。

页面右上角只有两个动作：

Promote cluster to regression test—— 把失败变成永远会跑的测试；
Ignore—— 已知限制、噪音、第三方故障，把 issue 藏起来，但不删 Trace。

从故障 Issue 到 CI 门禁：一键晋升回归测试 🧪

点Promote cluster to regression test后，Tracely 会从簇中冻结一条代表性失败 Trace，生成一个回归 case。晋升时自动捕获四样东西：

原始输入——用户请求原样保存，附带摘要保证同一输入不会被重复晋升；
Fixture bundle——该运行每一次工具调用、模型调用的参数与输出，存入对象存储，让 CI 里的重放"工具走录制、代码走真实"；
参考轨迹——失败运行实际走过的有序步骤；
Fail-to-pass 契约——候选运行必须满足的断言：无运行错误、必须真正执行哪些工具、工具序列是否必须匹配……

契约会先在源 Trace 上自证：那条失败运行必须"失败"自己的 case。如果原失败还能"通过"，说明这个 case 没抓住 bug，Tracely 直接拒绝创建。

晋升后的 case 进入该 agent 的 CI gate，之后每个 PR 都会重放它——bug 还在就红，修好就绿。

至此，31 条 Trace 暴露的故障有了完整可追踪的闭环：失败 → 自动聚类成 issue → 升成回归 case → CI 门禁拦住回归。

让新失败模式主动找你：配置告警 🚨

一个簇是"全新的"，恰恰是最值得打断人的信号——说明一种没人分诊过的失败模式刚出现在生产。在Alerts里配一条New failure mode触发器：任何新失败簇出现时，立即推送到 Slack、邮件或 Webhook。之后你打开 Failure clusters 页面时，已经是"带着答案"来的。

模块路径速查 📦

关注点	模块
结构签名：掩码、token 相似度、cluster key	backend/tracely/domain/failure/signature.py
UMAP + HDBSCAN 聚类引擎	backend/tracely/domain/failure/clustering.py
版本归因（introduced in）	backend/tracely/domain/failure/versions.py
语义聚类 + LLM 分析流水线	backend/tracely/services/failure_intel_service.py
集群 API（列表/详情/rebuild/promote/ignore）	backend/tracely/api/routers/clusters.py
晋升回归 case 的业务逻辑	backend/tracely/services/regression_service.py
产品设计文档（失败智能全景）	design/part2-tracely/07-failure-intelligence.md

常见问题 FAQ ❓

Q1：失败聚类需要配置模型吗？第一阶段（摄入时的结构签名）不需要任何模型，失败发生几秒后就能看到归组。第二阶段语义聚类（Analyze failures）需要工作区配置 OpenRouter key；没配置时按钮置灰，你保留结构簇即可。

Q2：为什么同一个失败会出现在两个簇里？结构签名阶段，措辞差异过大的 LLM judge 评语可能暂时拆出多个簇；点一次 Analyze failures 做语义重建后，第二轮合并/拆分会把它们整合成一个 issue。

Q3：修改了评估器（阈值、advisory）后，簇会跟着变吗？会。Cluster 本质上是 score 的视图——改完评估器后重跑聚类，下一轮结果自动反映变化，没有需要同步的第二份 issue 列表。

Q4：大量只出现一两次的噪音簇怎么处理？用列表页的Min occurrences过滤器（比如设为 3），只保留出现过至少 3 次的 issue；也可以对单个 issue 点Ignore，它从 open 计数中消失，但 Trace 不会被删除。

Q5：版本归因显示不出来怎么办？需要在tracely.agent(...)里带上version参数（git sha 也可以），且更早版本要有足够的干净运行（默认 20 条），Tracely 才会给出introduced in vX的结论，避免误导二分排查。

Q6：Issue 可以"修复"掉吗？Promote 成回归 case、修复部署、门禁持续绿灯后，就可以 Ignore 这个 issue——失败 Trace 依然可查，只是不再占用分诊注意力。

总结

Tracely 失败聚类的精髓在"两层机制 + 两个动作"：

两层机制：摄入时的廉价结构签名负责秒级归组，按需的 embedding + HDBSCAN + LLM 分析负责深度整合与成文结论；
两个动作：一个 Issue 要么Promote成永远重放的回归测试，要么Ignore掉；新失败模式还能直接触发告警。

下次生产环境再出现 31 条失败 Trace，打开 Failure clusters 页面——你看到的应该只是 1 个带时间线、带版本归因、带修复建议的故障 Issue，和一个随时可以拦下它复发的回归测试。

【免费下载链接】Tracely-ai

Trace-native CI/CD for AI agents: grade production traces, cluster failures, freeze them into replayable regression tests, and block PRs that regress. Self-hostable.

项目地址：https://gitcode.com/gh_mirrors/tr/Tracely-ai

点击查看免费下载