ambiguous-pointer commented on issue #1614:
URL: https://github.com/apache/dubbo-admin/issues/1614#issuecomment-6393192755

   ## 技术方案
   
   > 本评论是 #1612 周会条目 `trace的观测加强` 的落地方案。完整设计文档见分支上的 
`docs/ai-trace-observability-design.md`(656 行,含数据契约、错误边界、测试矩阵、分阶段与度量)。
   
   ---
   
   ## 一、总体架构
   
   ```text
                            ┌───────────────────────────────────────────┐
                            │            Dubbo Admin AI 助手           │
                            │         (ReAct Agent / Genkit)           │
                            └───────────────────┬───────────────────────┘
                                                │ MCP tool call
                
┌───────────────────────────────┼───────────────────────────────┐
                ▼                               ▼                               
▼
      ┌────────────────────┐        ┌────────────────────┐        
┌────────────────────┐
      │  search_traces     │        │   analyze_trace    │        │  
get_trace_by_id   │
      │  「找出链路」       │        │  「诊断链路」       │        │  「取原始 span」    │
      └─────────┬──────────┘        └─────────┬──────────┘        
└─────────┬──────────┘
                
└───────────────────────────────┼───────────────────────────────┘
                                                ▼
                                ┌───────────────────────────────┐
                                │   Provider 抽象(pkg/mcp/    │
                                │   tools/trace/provider.go)   │
                                │   GetTraceByID / SearchTraces │
                                └───────────────┬───────────────┘
                                                ▼
                                ┌───────────────────────────────┐
                                │  jaeger (v1 Query API)        │
                                │  /api/traces/{id}             │
                                │  /api/traces?service=...      │
                                └───────────────────────────────┘
   
      旁路关联(已存在,本 Issue 只做衔接):
        search_logs(traceId=...)   →  Loki
        query_prometheus(...)      →  Prometheus
   
      另一条链路:Admin 自身 Agent 的 OTLP 导出
        ai/component/hooks/tracing.go  →  OTLP  →  Jaeger
                                        └── 本 Issue 对齐 OTel GenAI 语义约定
   ```
   
   核心判断:**这是「AI assistant」章节的条目,交付物是 Agent 可用的能力,不是控制台页面**。因此不新增 Console 
API、不新增 Vue 页面、不动 Collector 与 Grafana。
   
   ---
   
   ## 二、如何实现 / 如何做到
   
   拆成四条可以并行推进、且互不阻塞的工作线。
   
   ### 2.1 工作线 A:Provider 侧检索(解决「找不到链路」)
   
   **做法**:扩展 `Provider` 接口,落地 Jaeger v1 Query API 的检索能力。
   
   ```go
   type Provider interface {
       GetTraceByID(ctx context.Context, traceID string) (*Trace, error)
       // 新增
       SearchTraces(ctx context.Context, query TraceSearchQuery) 
(*TraceSearchResult, error)
   }
   ```
   
   `jaeger` 是当前唯一实现,所以新增方法不影响其他后端;后续接 Tempo 只需再实现一个 Provider,**工具层一行不用改**。
   
   Jaeger v1 的 `/api/traces` 查询参数映射:
   
   | MCP 参数 | Jaeger 查询参数 | 说明 |
   | -- | -- | -- |
   | `service`(必填) | `service` | Jaeger 检索必须以服务为锚点 |
   | `operation` | `operation` | 按根操作名收窄 |
   | `traceId` | `traceID` | 锚定单条链路 |
   | `tags` | `tags`(JSON 对象) | 形如 `rpc.system=apache_dubbo`,采用 `k=v,k2=v2` 便于 
LLM 书写 |
   | `startTime` / `endTime` | `start` / `end`(unix 微秒) | RFC3339 输入 |
   | `minDurationMs` | `minDuration`(微秒) | 过滤掉短链路 |
   | `limit` | `limit` | 上限由后端与本地双重收敛 |
   
   **关键细节**:检索摘要必须基于**全部原始 span**计算,不能复用 `get_trace_by_id` 的归一化函数——后者会把 span 
裁剪到 `maxTraceSpans`(500) 并丢弃属性,那样根操作、错误数、服务集合就都不可信了。因此单独实现了一个只做摘要、不做细节裁剪的构造器。
   
   ### 2.2 工作线 B:链路诊断算法(解决「拿到链路也不知道问题在哪」)
   
   **做法**:在已归一化的 `Trace` 上做纯函数计算,产出结构化结论。纯函数意味着不需要后端就能测。
   
   **① Self time(自耗时)**
   
   一个 span 的自耗时 = 它自己的 duration 减去它**直接子 span 
覆盖的时间**。覆盖时间取子区间**裁剪到父区间后的并集**,因此重叠的子 span 不会被重复计算:
   
   ```text
   selfTime(parent) = duration(parent) − |⋃ [start(child), end(child)) ∩ 
[start(parent), end(parent))|
   ```
   
   `waitTime(parent) = duration(parent) − selfTime(parent)`,即父 span 在等子 span 
上花掉的时间。
   
   **② 关键路径**
   
   - 起点:在所有根 span 中取 **`end` 最大者**(决定链路墙钟终点的那条根),`end` 相同取 duration 大者,再相同取 
start 早者、span id 小者——保证结果确定。
   - 下降:从当前节点出发,在其子节点中取 **`end` 最大者**继续。理由是 `end` 最大的子 span 是父 span 
内**最后完成**的活动,它决定了父 span 的完成时刻。
   - 逐跳产出 `CriticalPathEntry{spanId, serviceName, operationName, startTime, 
durationMicros, selfMicros, waitMicros}`。链上 self time 之和即这条链路的「不可压缩耗时」。
   - 上限 32 跳 + visited 集合,成环不会死循环。
   
   **③ 服务维度耗时分解**
   
   按 `serviceName` 聚合 span 数、错误 span 数、总耗时、最大耗时、平均耗时与占比。占比的分母是链路墙钟时长,分子是各 span 
duration 之和——**并发场景下可能超过 100%**,这是「工作量占比」而不是互斥的时间切片,代码与文档里都做了标注。
   
   **④ 错误归因与根因**
   
   - 错误分类:`error.type` 优先,其次 `exception.type`;错误描述取 `exception.message`,其次 
`error.message`。
   - **根因判定:失败的 span 若没有任何失败的子孙,则它是根因**——也就是这个失败不是更深层失败冒泡上来的。根因排在列表最前。
   - 计数与列表**分离**:列表按 50 条封顶,但 `errorSpanCount` 始终是真实总数(provider 侧对全部 span 
统计过的计数优先),否则一条有 1000 个失败 span 的链路会被报成「50 个错误」。
   
   **⑤ 调用依赖边**
   
   对每条「父 span 属于服务 A、子 span 属于服务 B」的跨服务调用聚合一条边:调用次数、总耗时、错误次数。
   
   ### 2.3 工作线 C:GenAI 语义识别(解决「看不懂 trace 里的 LLM span」)
   
   **做法**:以 [OpenTelemetry generative AI 
语义约定](https://github.com/open-telemetry/semantic-conventions-genai) 为准(实现时钉在 
commit `6fd0d76`),识别并归类 `gen_ai.*` span。
   
   | 判定 | 规则 |
   | -- | -- |
   | 是否 GenAI span | 属性 key 以 `gen_ai.` 开头(大小写不敏感) |
   | 模型调用 | `gen_ai.operation.name ∈ {chat, generate_content, text_completion, 
embeddings, fetch_response}`,或携带 model / token 属性 |
   | 工具调用 | `gen_ai.operation.name == execute_tool`,或携带 `gen_ai.tool.name` |
   | Agent span | `gen_ai.operation.name ∈ {invoke_agent, create_agent, 
invoke_workflow, plan}`,或携带 `gen_ai.agent.name` |
   
   一个 span 只归一类(模型 > 工具 > Agent > 模型属性兜底)。
   
   **token 口径**:约定里**没有** `gen_ai.usage.total_tokens`,总量只有输入和输出两个属性,所以总量按 
`input + output` 计算;若某个 provider 真的发了 `gen_ai.usage.total_tokens`,则作为覆盖值尊重它。
   
   **trace kind**:链路中只要有任一 span 带 `gen_ai.*` 属性,检索摘要里的 `traceKind` 就是 
`"genai"`,Agent 便知道这条链路的性质。
   
   
**识别出的属性集**:`gen_ai.operation.name`、`gen_ai.provider.name`、`gen_ai.request.model`、`gen_ai.response.model`、`gen_ai.conversation.id`、`gen_ai.agent.name/id/description/version`、`gen_ai.tool.name`、`gen_ai.tool.call.id`、`gen_ai.usage.input_tokens`、`gen_ai.usage.output_tokens`
 及 cache/reasoning 
分项、`gen_ai.response.finish_reasons`、`gen_ai.response.id`、`gen_ai.data_source.id`、`gen_ai.output.type`。
   
   
内容类属性(`gen_ai.input.messages`、`gen_ai.output.messages`、`gen_ai.tool.call.arguments/result`)**分析器不读取**——它们是
 Opt-In 的敏感内容,且对诊断没有必要。
   
   ### 2.4 工作线 D:Agent 侧 trace 对齐(解决「自己的链路自己认不全」)
   
   **做法**:按语义约定修正 `ai/component/hooks/tracing.go` 的属性与事件。
   
   | 改动 | 依据 | 说明 |
   | -- | -- | -- |
   | 新增 `gen_ai.agent.name` = `dubbo-admin-sre-agent`,发在 invoke_agent 与 
execute_tool span 上 | `gen-ai-agent-spans.md`(invoke_agent 上 Conditionally 
Required) | 补上 Agent 身份,分析器才能命名 |
   | invoke_agent span 名改为 `invoke_agent {gen_ai.agent.name}` | 
`gen-ai-agent-spans.md`:`invoke_agent {gen_ai.agent.name}` if readily available 
| 规范形状 |
   | 失败 span 的 `error.type` 兜底为 `_OTHER` | `gen-ai-spans.md`:失败的 GenAI span 
必须有非空低基数 `error.type` | 之前 `state.ErrorType` 为空时整个属性缺失 |
   | 新增 `gen_ai.client.operation.exception` 事件,带 `exception.type` / 
`exception.message` / `exception.stacktrace` | `gen-ai-exceptions.md`:事件名 MUST 
为 `gen_ai.client.operation.exception` | 保留原有的 `span.RecordError` + 
`SetStatus(codes.Error)` |
   | `gen_ai.provider.name` 仅在模型串有 `provider/` 前缀时发 | 避免发出无意义取值 | 
未做白名单映射,见「未决问题」 |
   | 不发 `gen_ai.usage.total_tokens` | 约定里没有这个属性 | 总量继续用 Dubbo Admin 自有的 
`agent.usage.total_tokens` |
   
   **异常事件去重**:Agent 对一次失败的操作会同时发 `*.error` 与 `*.end` 两个事件,两者都带 error。实现上用一个按 
`(traceID, spanID)` 记账的记录器,保证**每个失败操作只记录一次** GenAI 异常事件;span 结束时释放记账,避免无限增长。
   
   **已知偏差**:约定要求异常事件 severity 为 WARN(13),但 OTel Go SDK 的 `sdk/trace.Event` 只携带 
`Name / Attributes / Time`,`trace.EventOption` 只接受属性与时间戳且不可在包外实现,因此 **WARN 
无法表达**,当前以 span status = Error 兜底(这正是约定引用的 Recording Errors 文档所要求的)。代码里有注释说明。
   
   ### 2.5 贯穿四条工作线的约束:有界响应
   
   本包原有的姿态是「任何返回给 Agent 的数据都必须有界」。新增能力完整继承:
   
   | 约束 | 取值 |
   | -- | -- |
   | 链路 span 数 | 500(`maxTraceSpans`,既有) |
   | 检索结果数 | 50(`maxTraceSearchResults`),超出走 `truncated` |
   | 关键路径跳数 | 32 |
   | 最慢 span / 错误 span / GenAI 明细 | 10 / 50 / 50,各自截断时置 `truncated` |
   | 响应体 | 8 MiB,超出直接报错 |
   | 单个属性值 | 512 字节,按 UTF-8 边界截断 |
   | 错误类型 / 错误描述 | 96 / 256 字符 |
   | 摘要文案 | 300 字符 |
   
   凭据处理:bearer token 只进请求头,`X-Scope-OrgID` 同理;失败日志只记录 provider 
名、服务名、耗时、错误类型与上游状态码,**不记录查询负载与凭据**;traceId 在日志中只保留末 8 位。
   
   ---
   
   ## 三、需要改动哪些文件
   
   ### 新增(7)
   
   | 文件 | 行数 | 内容 |
   | -- | -- | -- |
   | `pkg/mcp/tools/trace/search.go` | 175 | `SearchTraces` MCP 
handler、`SearchProperties()`、`buildTraceSearchQuery` 与标签/时间解析 |
   | `pkg/mcp/tools/trace/search_test.go` | 475 | 11 
个用例:请求路径与参数、鉴权头、摘要归一化与排序、genai kind、tags 序列化、service 必填、上游 500、截断、参数解析表驱动 |
   | `pkg/mcp/tools/trace/analyzer.go` | 720 | `AnalyzeTrace` 
handler、`AnalyzeProperties()`、`BuildTraceAnalysis` 及全部算法 |
   | `pkg/mcp/tools/trace/analyzer_test.go` | 400 | 14 
个用例:线性链、分支关键路径、根因归属、服务分解、依赖边、孤儿 span、环形父子引用、畸形时间戳、错误计数封顶 |
   | `pkg/mcp/tools/trace/genai.go` | 336 | 
`HasGenAISpans`、`HasGenAIAttributes`、`BuildGenAISummary` |
   | `pkg/mcp/tools/trace/genai_test.go` | 285 | 9 个用例:chat/tool/agent 归类、token 
口径、截断标记 |
   | `docs/ai-trace-observability-design.md` | 656 | 设计文档 |
   
   ### 修改(10)
   
   | 文件 | 改动 |
   | -- | -- |
   | `pkg/mcp/tools/trace/model.go` | 新增 `TraceSearchQuery` / 
`TraceSearchResult` / `TraceSummary` / `TraceAnalysis` 及 7 个子结构(后端无关的数据契约) |
   | `pkg/mcp/tools/trace/provider.go` | `Provider` 接口新增 `SearchTraces` |
   | `pkg/mcp/tools/trace/jaeger.go` | Jaeger v1 `/api/traces` 
检索实现、`buildJaegerTraceSummary` 摘要构造、`logSearchFailure` |
   | `pkg/mcp/register.go` | 注册 `search_traces`、`analyze_trace` |
   | `pkg/mcp/register_test.go` | 注册表用例补两项 |
   | `pkg/mcp/DEVELOPMENT.md` | 工具清单补两行 |
   | `ai/component/hooks/tracing.go` | 对齐 GenAI 语义约定(属性 + 事件 + span 名) |
   | `ai/component/hooks/tracing_test.go` | 新增 5 个用例 + 事件断言辅助函数 |
   | `ai/component/hooks/jaeger_e2e_test.go` | 父 span 映射跟随 span 改名同步 |
   | `ai/component/hooks/README.md` | 文档中的 span 名同步 |
   
   
**明确不动**:`pkg/console/handler/observability.go`、`pkg/config/observability/tracing.go`、`pkg/mcp/tools/log/`、`pkg/mcp/tools/metrics/`、`release/kubernetes/monitoring/`(Collector
 与 Grafana 配置)、`ui-vue3/`。
   
   ### 数据契约
   
   ```go
   // pkg/mcp/tools/trace/model.go
   type TraceSearchQuery struct {
       Service, Operation, TraceID string
       Tags map[string]string
       StartTime, EndTime time.Time
       Limit int
       MinDuration time.Duration
   }
   
   type TraceSearchResult struct {
       Traces []TraceSummary
       Total int
       Truncated bool
       SourceEngine string
   }
   
   type TraceSummary struct {
       TraceID, RootService, RootOperation, StartTime string
       DurationMicros int64
       SpanCount, ErrorSpanCount, ServiceCount int
       HasError bool
       TraceKind string        // "genai" 表示含 gen_ai.* 属性
   }
   
   type TraceAnalysis struct {
       TraceID, Summary, StartTime string
       DurationMicros int64
       SpanCount, ServiceCount, ErrorSpanCount int
       CriticalPath []CriticalPathEntry
       ServiceBreakdown []ServiceLatency
       SlowSpans []SlowSpan
       ErrorSpans []ErrorSpan
       Dependencies []DependencyEdge
       GenAI *GenAISummary
       Truncated bool
   }
   ```
   
   ### MCP 工具签名
   
   | 工具 | 必填参数 | 可选参数 | 返回 |
   | -- | -- | -- | -- |
   | `search_traces` | `service` | 
`operation`、`traceId`、`tags`、`startTime`、`endTime`、`minDurationMs`、`limit`、`provider`
 | `TraceSearchResult` |
   | `analyze_trace` | `traceId` | `provider` | `TraceAnalysis` |
   
   AI 侧无需改动即可拿到新工具:`ai/component/tools/engine/mcp_tools.go` 通过 `tools/list` 
全量自动注册,仓库里**没有** MCP 工具白名单。
   
   ---
   
   ## 四、如何设计的
   
   ### 4.1 为什么是「先发现,后分析」
   
   链路诊断的算法再准,输入也是一个 traceId。而 traceId 是人肉从日志/告警里捞出来的,**它从来不是 Agent 
能自己拿到的信息**。所以必须先补检索,否则诊断能力永远只能服务于「人已经知道要查哪条链路」的场景。
   
   同时 `search_traces` 的返回是**摘要**而不是完整链路:Agent 
的第一步只需要知道「有哪些候选、哪个有错、大概多慢」,把昂贵的链路拉取留到确实要看的那一条。
   
   ### 4.2 为什么诊断是纯函数
   
   `BuildTraceAnalysis(trace *Trace) *TraceAnalysis` 是纯函数,输入是已归一化的 
`Trace`,输出是结论。这带来三个好处:可以在没有后端的情况下做完整的算法单测;将来加 Tempo provider 
时分析逻辑一行不用改;算法与传输解耦,不会出现「provider 特殊行为污染诊断」。
   
   ### 4.3 为什么用 OTel GenAI 语义约定而不是自定义属性
   
   自定义一套 `ai.model.*` 之类的私有命名空间,短期看更省事,但有三个具体代价:
   
   1. **自己的分析器认不全**——私有命名空间不通用,跨项目复用时无法与社区工具(Langfuse / Phoenix / SigNoz)对齐;
   2. **无法被 Jaeger / Grafana / OTel Collector 的通用能力识别**——下游做 trace→metric 关联、做 
GenAI 面板时需要额外写映射;
   3. **约定本身在演进**——语义约定是 Development 状态且在快速变化(`gen_ai.client.token.usage` 
被移除、`gen_ai.operation.time_to_first_chunk` 改名、cache token 
属性多次调整)。跟随官方约定意味着**我们自动继承它的修订**,而不是自己维护一套又会过时的私有规范。
   
   代价是必须接受「约定还在动」这个事实,所以实现时钉死了 commit,并在文档里标注了全部文档的 Status。
   
   ### 4.4 为什么分析器不读内容类属性
   
   
`gen_ai.input.messages`、`gen_ai.output.messages`、`gen_ai.tool.call.arguments/result`
 都是 Opt-In 
的提示词与工具入参/返回。它们对「慢在哪、错在哪」的诊断没有帮助,却是最敏感的数据。分析器只读**元数据**(操作类型、模型、provider、token 
数、耗时、状态),内容留在采集侧由 capture policy 控制。
   
   ### 4.5 错误计数与错误列表为什么分开
   
   `ErrorSpans` 列表按 50 条封顶是出于 payload 有界性;但 `ErrorSpanCount` 如果也跟着封顶,就会把「1000 
个失败 span」报成「50 个错误」,Agent 会得出完全错误的判断。所以:**列表封顶,计数不封顶**,并且 provider 侧对全部原始 span 
统计的计数优先。
   
   ### 4.6 边界与非目标
   
   - 不新增 Console API / Vue 页面(给人看的仍是 Grafana 面板)。
   - 不动 Collector pipeline 与 Grafana datasource(属于 #1606 / PR #1607)。
   - 不新增 provider 类型(`jaeger` 仍是唯一实现,但接口已为后续扩展留好口子)。
   - 不做 trace 长期存储、异常检测、跨链路聚合。
   - 不追求 GenAI 约定的完全实现。
   
   ---
   
   ## 五、测试策略
   
   | 层 | 覆盖内容 |
   | -- | -- |
   | Provider 检索 | 请求路径与查询参数、鉴权与租户头、空参数省略、tags 序列化为 JSON 对象、上游错误码、结果截断、摘要排序确定性 |
   | 参数解析 | `startTime`/`endTime` RFC3339、`minDurationMs`、tags 畸形对、缺 `service` 
的报错 |
   | 诊断算法 | 线性链、分支场景关键路径落在慢分支、根因归属、服务分解数值与排序、跨服务依赖边、孤儿 span、环形父子引用不挂死、畸形 
`StartTime` 不 panic |
   | GenAI 识别 | chat / execute_tool / invoke_agent 归类、token = 输入 + 输出、无 GenAI 
属性时摘要为空、截断标记 |
   | Agent hook | `gen_ai.agent.name` 落位、span 改名、`error.type` 兜底 
`_OTHER`、异常事件属性、异常事件去重、内容 capture 策略不变 |
   | 回归 | `get_trace_by_id` / `search_logs` / `query_prometheus` 
行为不变;`pkg/mcp/...` 与 `ai` 模块全量测试 |
   
   验证命令:
   
   ```shell
   go build ./... && go vet ./pkg/... && go test ./pkg/mcp/...
   cd ai && go build ./... && go vet ./... && go test ./component/hooks/...
   ```
   
   ---
   
   ## 六、分阶段
   
   | 阶段 | 内容 | 退出标准 |
   | -- | -- | -- |
   | **Phase 1(P0 主体)** | 检索能力 + 诊断算法 + GenAI 识别 + Agent 侧对齐 + 单测 | 
`pkg/mcp/tools/trace/...` 与 `ai` 模块测试全绿;MCP `tools/list` 出现 `search_traces` / 
`analyze_trace`;在接入真实 Jaeger 的环境中,Agent 能在**零人工 traceId** 的前提下回答「最近一小时 X 
服务的失败链路有哪些」;`get_trace_by_id` 无回归 |
   | **Phase 2** | 与 #1537 的日志面板、#1606 的 Collector 标签对齐:`analyze_trace` 
输出补齐可直接用于 PromQL 的维度(服务名、接口名、方法名) | Agent 能从一条链路直接生成可执行的 PromQL 与 LogQL |
   | **Phase 3** | 更深的能力:exemplars / spanmetrics 关联、多 provider(Jaeger v2 / 
Tempo)、跨链路的错误模式聚合 | 单次排查可覆盖多个 provider;同源错误能跨链路聚类 |
   
   ---
   
   ## 七、未决问题(希望在周会确认)
   
   1. **`gen_ai.provider.name` 的白名单映射**:当前从模型串按 `/` 切分,会产出 `azure` 而非规范枚举 
`azure.ai.openai`。是否引入一张 provider 前缀 → 规范枚举的映射表?(约定本身**没有**规定如何从模型串推导 
provider,所以这张表需要我们自己维护。)
   2. **是否需要把 trace 检索同时暴露成 Console API**?本次只做 Agent 
能力。如果希望人类也能在控制台里直接搜链路,那应该另开条目并走 Console API / Vue 的流程。
   3. **采样缺口**:若生产环境对 trace 做了低比例采样,Agent 按时间窗检索会拿到不全的候选。是否需要向 Agent 
暴露采样率信息以避免误判「没有失败链路」?
   4. **token 成本**:GenAI 约定已经不再提供 `gen_ai.usage.total_tokens`,而成本核算往往需要总量。本 
Issue 按 `输入 + 输出` 计算,是否需要额外保留一个 Dubbo Admin 自有的总量属性?
   5. **WARN severity 缺位**:OTel Go SDK 无法表达事件 severity。是接受 span status = Error 
的兜底,还是等 SDK 支持后跟进?
   6. **多 provider 的优先级**:Phase 3 若同时接入 Jaeger 与 Tempo,Agent 的工具参数是否需要支持「同时查多个 
provider 并合并结果」?
   


-- 
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]

Reply via email to