ambiguous-pointer opened a new pull request, #1618: URL: https://github.com/apache/dubbo-admin/pull/1618
## 概要 让 AI 助手能**自主发现并诊断** Dubbo 业务的分布式链路:不需要人先提供 traceId,助手自己按服务与时间窗找出候选链路,再算出关键路径、服务维度耗时、错误根因与调用依赖。 > 这是周会条目「trace 的观测加强」中 **Agent 去诊断业务链路** 的那一半。 > **Agent 自身行为的可观测性**(怎么调用的、用了哪些 tools、思考过程、输入输出)是另一件事,见 #1616。 --- ## 为什么需要 助手能查日志、能查指标,唯独不能查链路——只要问题停在「最近 X 服务有没有失败请求」这一层,它就必须先把问题退回给用户索要 traceId,观测能力形同虚设。 即使拿到了 traceId,原始 span 也是**事实**而不是**结论**: - 哪个 span 真正消耗了时间?原始 span 只有各自的 duration,看不出父子之间的等待关系; - 慢在哪个服务?并发场景下各服务耗时会重叠,不能直接相加; - 错误是根因还是被冒泡?上游往往因为下游失败而一起标红,但根因只有一个; - 服务之间的调用关系?隐含在 `parentSpanId` 里,没有被提炼出来。 Agent 需要的是**结论**,否则它拿到一堆 span 还是要自己做一遍精确的时间轴推理,而 LLM 做这件事非常不可靠。 --- ## 改了什么 | 能力 | 说明 | | --- | --- | | `search_traces` | 按服务、操作、traceId、标签、时间窗、最小耗时检索链路,返回有界的逐条摘要(根服务与操作、耗时、span 数、错误 span 数、服务数、是否含错误、是否 GenAI 链路) | | `analyze_trace` | 把一条链路变成结论:延迟关键路径(每跳的 self time 与 wait time)、服务维度耗时分解、最慢 span、失败 span 及其错误分类与根因标记、调用依赖边 | | `Provider.SearchTraces` | Provider 接口新增检索方法,接入新后端不需要动工具层 | ### 关键设计 **先发现,后分析。** 助手能查日志、能查指标,唯独不能查链路——只要问题停在「最近 X 服务有没有失败请求」这一层,它就必须先把问题退回给用户索要 traceId,观测能力形同虚设。所以第一件事是让 provider 支持检索,而不是先去做更复杂的分析。 **诊断逻辑做成纯函数。** `BuildTraceAnalysis(trace *Trace) *TraceAnalysis` 输入是已归一化的 `Trace`,输出是结论。好处有三个:算法可以完全脱离后端做单测;将来接入 Tempo 时分析逻辑一行不用改;算法与传输解耦,不会被某个 provider 的特殊行为污染。 **self time 用区间并集算,不重���。** 一个 span 的总时长里大部分可能是它在等子 span。self time = 总时长减去子 span 覆盖区间的**并集**(重叠的子 span 不能重复计数)。 **关键路径走「结束时间最晚」的那一支。** 从「结束最晚的根」出发,每一跳走向「结束最晚的子节点」——那是父 span 内最后完成的活动,决定了父 span 的完成时刻。 **错误根因 = 没有失败后代的失败 span。** 上游 span 往往因为下游失败而一起标红,但根因只有一个。判据是「它的子树里还有没有别的失败 span」。 **摘要基于全部原始 span,细节路径维持原样。** `get_trace_by_id` 的归一化会把 span 裁剪到 500 条并丢弃属性——那是它作为「取原始链路」工具的合理取舍。但检索摘要若复用这条路径,根操作名、错误数、服务集合就都不可信了。所以摘要单独实现,遍历**全部**原始 span;而 `get_trace_by_id` 的行为**完全未变**,避免对已发布工具造成回归。 **有界响应。** Agent 的上下文是有限的。所有列表都有上限,所有截断都会在 payload 里显式标记,让 Agent 能区分「数据完整」与「数据不完整」。 **凭据不进工具结果。** 传输错误在写日志前解包(Go 的 `*url.Error` 会把完整请求 URL 写进 message,其中含检索条件与 traceId),只保留 `dial tcp ...` 这类诊断信息。 --- ## 验证 `go build ./... && go vet ./pkg/... && go test ./pkg/...` 全绿,trace 包 71 个用例。 覆盖:检索的参数映射与摘要归一化、genai kind 识别、上游错误、结果截断;诊断的线性链、分支场景关键路径落在慢分支、根因归属、服务分解、依赖边、孤儿 span、**父子引用成环不挂死**、畸形时间戳、**错误计数不被列表上限截断**;GenAI 归类与 token 口径。 --- ## 不在本 PR 范围 - Agent 自身行为的可观测性与采集端可视化(见 #1616) - trace 检索暴露为 Console API - 多 provider 检索合并 - 与日志、指标的联动 --- ## 关联 - 周会条目:https://github.com/apache/dubbo-admin/discussions/1612 - Issue:https://github.com/apache/dubbo-admin/issues/1614 - Agent 自身的可观测性:#1616 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
