ambiguous-pointer opened a new pull request, #1616:
URL: https://github.com/apache/dubbo-admin/pull/1616
## 概要
让 AI 助手能**自主发现并诊断**链路,并把 Agent 自身的 trace 对齐到 OpenTelemetry 的 generative AI
语义约定。
之前助手只能按 traceId 取链路,且必须先知道 traceId 是什么——而 traceId
只能由人从日志/告警里捞出来。这次补上了「先发现、后分析」这条闭环。
> 中文版:本次改动包含三部分——① `pkg/mcp/tools/trace` 增加链路检索与诊断两个 MCP 能力;②
`ai/component/hooks` 按 OTel GenAI 语义约定对齐 Agent 自身的 trace;③ 有界响应与凭据处理。
---
## 为什么这样写
### 1. 先发现,后分析
助手能查日志、能查指标,唯独不能查链路——只要问题停在「最近 X 服务有没有失败请求」这一层,它就必须先把问题退回给用户索要
traceId,观测能力形同虚设。所以第一件事是让 provider 支持检索,而不是先去做更复杂的分析。
### 2. 诊断逻辑做成纯函数
`BuildTraceAnalysis(trace *Trace) *TraceAnalysis` 是纯函数,输入是已归一化的
`Trace`,输出是结论。好处有三个:算法可以完全脱离后端做单测;将来接入 Tempo 时分析逻辑一行不用改;算法与传输解耦,不会被某个 provider
的特殊行为污染。
### 3. 摘要基于全部原始 span,细节路径维持原样
`get_trace_by_id` 的归一化会把 span 裁剪到 500
条并丢弃属性——那是它作为「取原始链路」工具的合理取舍。但如果检索摘要复用这条路径,根操作名、错误数、服务集合就都不可信了。所以摘要单独实现,遍历**全部**原始
span;而 `get_trace_by_id` 的行为**完全未变**,避免对已发布工具造成回归。
### 4. 关键路径用 self time,而不是 span 总时长
一个 span 的总时长里,大部分可能是它在等子 span。真正阻塞请求的是 self time = 总时长减去子 span
覆盖区间的**并集**(重叠的子 span 不能重复计数)。关键路径从「结束时间最晚的根」出发,每一跳走向「结束时间最晚的子节点」——因为那是父 span
内最后完成的活动,决定了父 span 的完成时刻。
### 5. 错误根因 = 没有失败后代的失败 span
上游 span 往往因为下游失败而一起标红,但根因只有一个。判据是「它的子树里还有没有别的失败 span」——有就说明它只是错误传播的中间环节。
### 6. 遵循 OTel GenAI 规范,而不是自造私有命名空间
这是整个特性里最重要的一个取舍。如果用私有的 `ai.model.*`
之类命名空间,短期省事,但代价有三个:自己的分析器认不全、Jaeger/Grafana/Collector 的通用能力识别不了、每个后端都要写一层适配。
跟随官方约定的直接收益已经被实测验证:**OpenLIT 把 `invoke_agent dubbo-admin-sre-agent` 识别成一条
Coding Agent 链路并重建了完整 span 树;Langfuse 把 `gen_ai.conversation.id` 映射成自己的
`sessionId`。** 我们没有写任何一行适配代码。
### 7. `gen_ai.agent.name` 与 invoke_agent 的 span 名
规范要求 invoke_agent span 以 `invoke_agent {gen_ai.agent.name}` 命名。缺少 agent
名字时,链路在可观测平台里就只是一个匿名的 span——分析器能识别出「有个 Agent span」,但叫不出它是谁。名字取
`dubbo-admin-sre-agent` 这个稳定常量,而不是每次运行的值。
### 8. 异常事件用规范规定的名字
GenAI 侧的异常事件名必须是 `gen_ai.client.operation.exception`,携带 `exception.type` /
`exception.message` / `exception.stacktrace`。同时**保留**了标准 `exception` 事件——Dubbo
RPC 链路里全是传统异常事件,分析它们是分析器的基本盘。两个事件不冲突:一个是 GenAI 语义面,一个是通用 OTel 异常面。
### 9. `error.type` 兜底为 `_OTHER`,而不是错误原文
规范要求失败的 GenAI span 必须有非空、低基数的 `error.type`。把整段错误信息塞进 `error.type`
会直接破坏基数——那正是 `_OTHER` 这个 well-known 值存在的意义。
### 10. `capture_reasoning` 与 `capture_content` 分开
它们是两类不同的风险:提示词与工具入参/返回值是**业务数据**;模型思考过程是另一类内容。合成一个开关,就没法做到「开发期要看思考过程、生产期要藏起来」的同时又不误开业务数据。规范里思考过程就装在
`gen_ai.input.messages` / `gen_ai.output.messages` 的 `reasoning` part
中,**不需要新造属性**——当前实现的问题是转换时把这个 part 直接丢掉了。
### 11. 移除私有的 `agent.usage.total_tokens`
规范只定义了输入和输出两个 token 属性,总量是它们的和。再维护一个私有总量,等于对同一个数字给出两套可能不一致的定义;而且成本核算是企业 API
网关的事(网关持有 key),Admin 只需要给出「模型名 + token 数」。
### 12. provider 白名单是一张小别名表,不是过滤器
规范原文允许自定义值("otherwise, a custom value MAY be used"),所以**不能**把枚举外的 provider
过滤掉——那会让 `dashscope`、`siliconflow` 这类值凭空消失。只对规范里有明确依据、且无歧义的情况做修正(`gemini` →
`gcp.gemini`,依据是 base_url 为 `generativelanguage.googleapis.com`,而规范对
`gcp.gemini` 的描述正是 "Also known as the AI Studio API")。
### 13. 有界响应
Agent 的上下文是有限的。所有列表都有上限,所有截断都会在 payload 里显式标记,让 Agent
能区分「数据完整」与「数据不完整」,而不是把一份被裁剪的结论当成完整结论。
### 14. 传输错误在写日志前解包
Go 的 `http.Client` 返回的 `*url.Error` 会把完整请求 URL 写进 error message,其中包含检索条件与
traceId。日志侧解包成内层错误,只保留 `dial tcp ...` 这类真正有用的信息。
>
关于**工具返回**:按设计保留上游错误原文——工具结果本就要进入模型上下文,用户可以直接追问「上一次调用的模型与返回结果是什么」。其中可能携带的业务敏感数据目前**没有过滤机制**,已记为待办
T7。
---
## 变更内容
| 区域 | 内容 |
| --- | --- |
| `pkg/mcp/tools/trace` | 新增
`search_traces`(按服务/操作/时间窗/标签检索)、`analyze_trace`(关键路径、服务维度耗时、最慢
span、错误根因、依赖边)、GenAI 属性识别;`Provider` 接口新增 `SearchTraces` |
| `ai/component/hooks` | `gen_ai.agent.name`、invoke_agent span
改名、`error.type` 兜底、`gen_ai.client.operation.exception` 事件、`capture_reasoning`
策略、provider 取值映射、移除私有 token 总量 |
| `docs/ai-trace-observability-design.md` | 设计文档:背景、契约、算法、错误边界、安全、测试矩阵、分阶段计划
|
---
## 验证
**单元测试**:root 模块 `go build ./... && go vet ./pkg/... && go test ./pkg/...` 与
ai 模块 `go build ./... && go vet ./... && go test ./...` 全绿;trace 包 71 个用例,hooks
包 38 个用例。
**真实采集平台验证**:在本地统一收集点(OTel Collector → OpenLIT / Langfuse / Greptime)上连续跑 3
次完整 Agent 交互(invoke_agent → iteration → stage → 模型调用 + 2 个工具调用,其中一个失败),3/3
全部入库,18/18 span 无缺失:
- span 层级与父子关系完整,`chat` span 的 SpanKind 为 Client,失败工具 span 状态为 Error
- `gen_ai.provider.name = gcp.gemini`(映射生效)、`gen_ai.agent.name =
dubbo-admin-sre-agent`
- 每次运行恰好一条 `gen_ai.client.operation.exception` 事件(去重正确)
- `gen_ai.output.messages` 中 reasoning part 形状为 `{"type":"reasoning"}`(符合规范)
- OpenLIT 将其识别为 Coding Agent 并重建 span 树,Chat 视图还原完整对话
- Langfuse 映射出 `sessionId = gen_ai.conversation.id`
> 过程中发现两个与本改动无关但值得知晓的事实:采集点的 `tail_sampling` 只有 `errors-always` /
`slow-always(≥2s)` / `probabilistic-10%` 三条策略,无错误且不够慢的链路会被 10%
概率采样丢弃——这正是「检索结果需要携带采样信息」这条待办的由来;另外 span 必须有配对的结束事件才会被导出。
---
## 不在本 PR 范围
- trace 检索暴露为 Console API(控制台已有 Grafana 面板,再做一套会造成页面与日志冗余)
- 多 provider 检索合并(需要先有第二个 provider 才有意义)
- GenAI 异常事件的 severity 表达(Go SDK 的 span 事件结构上没有 severity 字段)
- 工具返回的敏感内容过滤机制
- MCP Server 侧接收 trace context(让 Admin 自身的调用进入 Agent 链路)——建议单独 PR
---
## 关联
- 周会条目:https://github.com/apache/dubbo-admin/discussions/1612
- Issue:https://github.com/apache/dubbo-admin/issues/1614
- 2026 路线图:https://github.com/apache/dubbo-admin/discussions/1386
- 互补工作:trace 与 Dubbo 指标关联 https://github.com/apache/dubbo-admin/issues/1606
、日志可观测与联动 https://github.com/apache/dubbo-admin/issues/1537
- 规范来源:https://github.com/open-telemetry/semantic-conventions-genai (实现时钉在
`6fd0d76`,全部文档 Status 为 Development)
--
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]