ambiguous-pointer opened a new issue, #1614: URL: https://github.com/apache/dubbo-admin/issues/1614
## 来源 2026-10-24 周会 [Discussion #1612](https://github.com/apache/dubbo-admin/discussions/1612) 的 **AI assistant** 章节记录了如下待办: | task | owner | 等级 | 进度 | issue/discussion | pr | | -- | -- | -- | -- | -- | -- | | trace的观测加强 | luoyi | P0 | 待开始 | - | - | 对照 2026 路线图 [Discussion #1386](https://github.com/apache/dubbo-admin/discussions/1386): - **AI / SRE Agent** 第 7 项「设计Hook系统,接入otel trace」——Agent 自身已通过 `ai/component/hooks/tracing.go` 接入 OTel,但缺少把 trace 数据**回喂给 Agent 自己**的能力。 - **可观测能力** 第 3 项「基于Grafana,探索metric,trace,log的联动」——这是**给人**的 Grafana 联动,与本 Issue 是互补关系。 该条目属于 **AI assistant** 章节而不是 Admin 控制台章节,所以交付物是 **Agent 可用的观测能力**,不是给人看的控制台页面。 --- ## 1. 为什么需要可观测性 ### 1.1 Admin 的定位决定了可观测性是它的基本盘 Dubbo Admin 是微服务集群的**控制面**,掌握全集群的运行时信息(应用、实例、服务、拓扑、规则)。2026 路线图把「可观测能力」和「服务治理能力」并列为两大方向。 但控制面有一条特殊约束:**Admin 自己的每一次操作都发生在用户的生产链路上**。用户在 Admin 上做的每一个动作——查看拓扑、下发路由规则、排查一次超时——背后都是真实的 Dubbo 调用链。Admin 自己如果不可观测,用户在排障时就得同时排两套问题,这会直接抵消 Admin 作为控制面的价值。 ### 1.2 对 AI 助手来说,可观测性决定了它是「问答机」还是「SRE」 路线图对 AI 的定位是「关注用户对话,Dubbo 领域的自治」。**自治的前提是能观测**:Agent 必须能自己发现异常、自己定位到根因、自己给出结论,而不是把问题原样退回给用户。 现在 Agent 已经有了一整套自主排查工具: | 数据类型 | Agent 侧已有工具 | 能否自主发现问题 | | -- | -- | -- | | 集群/实例/服务拓扑 | `get_cluster_info`、`search_services`、`get_service_instances`、`get_application_detail` … | 能 | | 日志 | `search_logs`、`analyze_error_logs`、`get_log_capabilities` | 能 | | 指标 | `query_prometheus`、`query_prometheus_range` | 能 | | **链路** | **只有 `get_trace_by_id`** | **不能** | 指标只能告诉你「有异常」,日志只能告诉你「报了什么错」,**只有 trace 能回答「慢在哪一段、错在哪一层、谁调谁」**。也就是说 Agent 能发现「这个服务变慢了」,却无法回答「是哪一跳变慢了」,只能反过来找用户要 traceId。 ### 1.3 Agent 自己的链路也必须是可观测的 Dubbo Admin 的 AI 助手通过 MCP 工具调用 Dubbo Admin 自己的 Console API,形成了一条真实的服务调用链。Agent 每一次 ReAct 迭代、每一次模型调用、每一次工具调用,本身都是一条需要被观测的链路——否则 Agent 出了问题(比如工具超时导致回答变慢)时,没有人能回答「这次会话慢在哪」。 这条链路的观测必须遵循 **OpenTelemetry 官方的 generative AI 语义约定**,否则 trace 里的模型调用、工具调用无法被通用工具识别,也无法与社区的后端(Langfuse / Phoenix / SigNoz)对齐。 --- ## 2. 当前遇到了什么困难 ### 2.1 链路是 Agent 观测能力的最后一块拼图,且完全缺失「发现」环节 `get_trace_by_id`(`pkg/mcp/tools/trace/tools.go`)要求调用方提供 `traceId`。而 `traceId` 是人肉从日志、告警或 Grafana 里捞出来的: ```text 用户:shop-order 最近变慢了,为什么? Agent:能查到 prometheus 指标在涨,也能拉到日志,但拿不到链路 → 请提供 traceId ``` 只要用户的问题停留在「最近 X 服务有没有失败的请求」「这个接口为什么变慢」这一层,Agent 就必须先把问题退回给用户索要 traceId,观测能力形同虚设。 **当前 `Provider` 接口只有 `GetTraceByID` 一个方法**(`pkg/mcp/tools/trace/provider.go`),没有任何 provider 侧的检索能力。 ### 2.2 即使拿到了 trace,原始 span 也回答不了「问题在哪」 `get_trace_by_id` 返回的是归一化后的原始 span 列表。原始 span 是**事实**,不是**结论**: - 哪个 span 真正消耗了时间?——原始 span 只有各自的 duration,看不出父子之间的等待关系。 - 慢在哪个服务?——需要跨 span 聚合,而且并发场景下各服务耗时会重叠,不能直接相加。 - 错误是根因还是被冒泡?——上游 span 往往因为下游失败而一起标红,但根因只有一个。 - 服务之间的调用关系是什么?——原始 span 的父子关系隐含在 `parentSpanId` 里,没有被提炼出来。 Agent 需要的是**结论**:关键路径在哪、瓶颈服务是谁、根因是哪个 span、调用依赖长什么样。否则它拿到一堆 span 还是要自己做一遍推理,而 LLM 做这种精确的时间轴推理非常不可靠。 ### 2.3 Agent 看不懂 trace 里的 LLM span Dubbo Admin 的 AI 助手本身就是 LLM Agent,它的 trace 里会同时存在两类 span: - Dubbo RPC span(`rpc.system=apache_dubbo`)——已经能理解; - 生成式 AI span(`gen_ai.*`)——**目前完全无法识别**。 这直接导致一个很实际的问题:**在 Agent 场景里,「失败」经常发生在模型调用或工具调用上,而不是 Dubbo RPC 上**。一条链路的根因可能是模型返回了非法 JSON,也可能是某个 MCP 工具超时。Agent 目前的分析视角里根本没有这类 span,等于对最主要的失败模式失明。 ### 2.4 Agent 自身的 trace 还不符合规范,无法被自己的分析器识别 `ai/component/hooks/tracing.go`(PR #1536 引入)已经会发出 `gen_ai.operation.name`、`gen_ai.request.model`、`gen_ai.provider.name`、`gen_ai.conversation.id`、`gen_ai.tool.name`、`gen_ai.tool.call.id` 和 token 用量,但对照 [OpenTelemetry generative AI 语义约定](https://github.com/open-telemetry/semantic-conventions-genai) 仍有明确差距: | 问题 | 现状 | 后果 | | -- | -- | -- | | 缺 `gen_ai.agent.name` | 未发 | 规范在 invoke_agent span 上把它列为 Conditionally Required;缺了它,Admin 自己的 Agent span 在链路里**没有身份**,分析器只能识别出「有一个 Agent span」,无法命名 | | invoke_agent span 名不合约 | `invoke_agent` | 规范要求 `invoke_agent {gen_ai.agent.name}`(agent name 可用时) | | 异常事件名不合约 | 用 `span.RecordError` 产生标准的 `exception` 事件 | 规范要求 GenAI 侧使用 `gen_ai.client.operation.exception` 事件,带 `exception.type` / `exception.message` / `exception.stacktrace` | | `error.type` 可能为空 | 仅当 `state.ErrorType` 非空时才发 | 规范要求失败的 GenAI span 必须有非空、低基数的 `error.type` | | `gen_ai.provider.name` 取值不合约 | 由 model 字符串按 `/` 切分推导,会产出 `azure` 这类非枚举值 | 规范枚举是 `azure.ai.openai` 等 16 个 well-known 值 | 结果就是:**Agent 发的 trace,自己的分析器也认不全**,闭环没有形成。 ### 2.5 与相邻工作流职责交叠,需要先把边界划清 | 已有工作 | 覆盖的层 | 与本 Issue 的关系 | | -- | -- | -- | | [#1606](https://github.com/apache/dubbo-admin/issues/1606) / PR [#1607](https://github.com/apache/dubbo-admin/pull/1607) | OpenTelemetry Collector OTTL transform + Grafana `tracesToMetrics` datasource | **互补**:它让 Grafana 能从 trace 跳到 metric,但明确不新增 Admin API、不新增 Agent 能力。Agent 依然无法自己发现和分析链路 | | [#1537](https://github.com/apache/dubbo-admin/issues/1537) / [#1524](https://github.com/apache/dubbo-admin/issues/1524) | 控制台日志面板、metric/trace/log 联动 | **互补**:那是给人看的控制台面;本 Issue 是给 Agent 用的 | | PR [#1499](https://github.com/apache/dubbo-admin/pull/1499) | `query_prometheus`、`query_prometheus_range`、`get_trace_by_id` | **前置**:已提供 PromQL 与取链路的基础,本 Issue 在其上补齐检索与诊断 | | PR [#1536](https://github.com/apache/dubbo-admin/pull/1536) | Agent 侧 OTel hook | **前置**:已具备发 trace 的能力,本 Issue 让它符合规范并可被自分析 | --- ## 3. 大致的产物效果 ### 3.1 Agent 的能力边界变化 | 能力 | 现在 | 完成后 | | -- | -- | -- | | 找链路 | **做不到**,必须由人给 traceId | `search_traces` 按服务/操作/时间窗/最小耗时检索,Agent 自主发现候选链路 | | 判链路 | 只能读原始 span | `analyze_trace` 直接给出关键路径、服务维度耗时、最慢 span、错误根因、调用依赖边 | | 看懂 LLM span | **做不到** | 自动识别 `gen_ai.*` span,汇总模型调用、provider、模型名、token 用量、工具调用、Agent span | | 排查自己的链路 | **做不到** | Agent 自身 trace 符合规范,能被同一套分析器识别 | ### 3.2 一次完整排障的形态 ```text 用户:shop-order 服务最近一小时有失败的请求吗? │ ├─ search_traces(service="shop-order", startTime=..., minDurationMs=500) │ → 命中 12 条链路,其中 3 条含错误 span │ ├─ analyze_trace(traceId="faba6a688ea3070b1613f50fb081c578") │ → 根因:payment-service/charge ERROR timeout │ 关键路径:gateway 12ms → order 35ms → payment 1842ms(自耗时占 92%) │ 服务维度:payment 占总 span 耗时的 76% │ 依赖边:order-service → payment-service(3 次,2 次失败) │ ├─ search_logs(traceId="faba6a688ea3070b1613f50fb081c578") │ → payment-service 的超时日志 │ └─ query_prometheus(query='sum by (application_name) (rate(dubbo_consumer_requests_total{...}[5m]))') → 确认请求量同步上涨,是下游容量问题而非本地 ``` ### 3.3 交付物形态 | 交付物 | 形态 | 面向 | | -- | -- | -- | | `search_traces` | 新增 MCP 工具,provider 侧检索链路 | Agent | | `analyze_trace` | 新增 MCP 工具,结构化链路诊断 | Agent | | GenAI 识别 | trace 内的 `gen_ai.*` span 归类与 token 汇总 | Agent | | Agent trace 对齐 | 补 `gen_ai.agent.name`、改 span 名、发 `gen_ai.client.operation.exception` 事件 | Agent 自身链路 | | 设计文档 | `docs/ai-trace-observability-design.md` | 评审与后续演进 | ### 3.4 明确不做 - 不新增 Console HTTP API、不新增 Vue 页面。**给人看的** trace 视图仍然走 Grafana 面板(`pkg/console/handler/observability.go`)。 - 不改动 Collector pipeline、不改 Grafana datasource 配置、不引入 spanmetrics / exemplars / service graph。这些属于 [#1606](https://github.com/apache/dubbo-admin/issues/1606) / PR #1607。 - 不新增 trace provider 类型。`jaeger` 仍是唯一 provider,只是 `Provider` 接口被扩展,后续接 Tempo 不需要动工具层。 - 不做 trace 的长期存储、异常检测或跨链路的聚合分析。 - 不追求 generative AI 语义约定的**完全**实现。该约定全部文档 Status 都是 **Development** 且仍在变动,本 Issue 只实现 Agent 诊断链路真正需要的子集。 --- ## 4. 验收标准(摘要) - [ ] `search_traces` 能按服务 + 时间窗返回链路摘要(根服务、根操作、耗时、span 数、错误 span 数、服务数),`service` 参数必填。 - [ ] 空结果是**成功的空列表**而不是错误;provider 未配置、链路不存在则是可读的错误。 - [ ] `analyze_trace` 返回带 self time / wait time 的关键路径,且关键路径确实落在决定端到端时延的那条分支上。 - [ ] 服务维度分解与最慢 span 排序稳定可重现;时间戳畸形、父 span 缺失、父引用成环都不会 panic 或挂死。 - [ ] 失败的叶子 span 被判为根因,其被冒泡的错误祖先不被判为根因。 - [ ] 含 `gen_ai.*` 属性的链路被识别:模型调用 / 工具调用 / Agent span 分开归类,token 总量 = 输入 + 输出;无 GenAI 属性的链路不返回 GenAI 摘要。 - [ ] Agent 自身 trace 发出 `gen_ai.agent.name`,invoke_agent span 名为 `invoke_agent {gen_ai.agent.name}`,失败 span 的 `error.type` 非空,且每个失败操作只记录一次 `gen_ai.client.operation.exception` 事件。 - [ ] 所有返回列表都有上限,截断在 payload 中显式标记,任何工具结果和日志行里都不出现 bearer token、tenant header 等凭据。 - [ ] `get_trace_by_id`、`search_logs`、`query_prometheus` 行为无回归。 --- ## 5. 关联链接 - 周会条目:https://github.com/apache/dubbo-admin/discussions/1612 - 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 - OSPP 可观测优化:https://github.com/apache/dubbo-admin/issues/1524 - OpenTelemetry generative AI 语义约定:https://github.com/open-telemetry/semantic-conventions-genai -- 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]
