chaojixinren commented on issue #1525:
URL: https://github.com/apache/dubbo-admin/issues/1525#issuecomment-5232060183
> **What would you like to be added**:您希望添加什么内容呢： Implement hook system in
admin agent，like middleware in langchain, hooks in claude code,
etc.在管理代理中实现钩子系统，就像 LangChain 中的中间件、Claude Code 中的钩子功能一样。 Based on the hook
system, inject trace and expose to outer otel-trace compatible backend like
jaeger, langfuse基于该钩子系统，可以注入追踪信息，并将这些信息传递给诸如 Jaeger、Langfuse 之类的、与 otel-trace
兼容的后端系统。
>
> **Why is this needed**: 为什么需要这样做呢：
# [Design Proposal] Hook 系统 + OTel Trace 导出
## 动机
agent 的 ReAct 管线(`Interact → runLoop → reasonAct/observe`)目前是运行时黑盒:
没有交互级关联(只有散落的日志行)、没有模型/工具的延迟与 token 成本可见性、
超时和降级回退被静默处理。且即将到来的横切需求(trace、metrics、审计、护栏、#1503 鉴权)
都没有统一的接入点,只能各自硬编码进策略代码。
参照 LangChain middleware / Claude Code hooks:**在 agent 循环周围建立稳定的事件边界**,
消费方订阅事件而不侵入策略;第一个消费方是 OTel tracing,经 OTLP 导出到
Jaeger(基础设施视角)/ Langfuse(LLM 视角,支持 GenAI 语义约定)。
## 总体结构
```mermaid
flowchart LR
subgraph loop["ReAct 执行循环"]
A[Interact] --> B[runLoop / iteration]
B --> C[stage: reasonAct]
C --> D[模型调用]
C --> E[工具调用 xN]
B --> F[stage: observe]
F --> G[模型调用]
end
loop -- "事件: Interaction / Iteration /<br/>Stage / ModelCall / ToolCall
(Start+End)" --> HM[HookManager<br/>hooks 组件, YAML 配置]
HM --> T[TracingHook<br/>OTel span + GenAI 语义约定]
HM --> L[LoggingHook<br/>按 interaction id 关联]
HM -.-> X[后续: metrics / 审计 / 拦截型护栏]
T --> OTLP[OTLP exporter]
OTLP --> J[Jaeger]
OTLP --> LF[Langfuse]
OTLP -.双后端同时导出.-> COL[OTel Collector 扇出]
```
**Hook 分两层**:观察型(MVP,只读回调,唯一允许的影响是 `*Start` 事件派生 ctx 以携带 span;
panic 一律 recover,永不破坏 agent)+ 拦截型(post-MVP,仅在模型/工具两个动作点上
middleware 链式包裹,可改写/短路,留给护栏场景)。作为新的 `hooks` runtime 组件接入,
在 `main.go` `registerFactorys` 中注册于 `agent` 之前(初始化顺序由注册顺序决定,
`e2e_test.go` 的第二个注册点需同步),HookManager 在 `AgentComponent.Init(rt)` 中解析注入。
## Span 层级与跨进程传播
```mermaid
flowchart TD
FE[前端请求<br/>traceparent 提取, trace id 回传] --> R
subgraph trace["一条 trace(每次交互)"]
R["interaction (root)<br/>session.id · 累计 token 用量"]
R --> I["iteration[n]"]
I --> S1["stage: reasonAct"]
S1 --> M1["model call<br/>gen_ai.request.* · gen_ai.usage.*"]
S1 --> T1["tool: query_metrics<br/>gen_ai.tool.name · degraded 标记"]
I --> S2["stage: observe"]
S2 --> M2["model call<br/>fallback_used 标记"]
end
T1 -- "HTTP 头注入 traceparent" --> MCP[远程 MCP server<br/>如 #1499 诊断工具,
接续同一 trace]
```
关键点:
- **Stage 事件是结构必需**:`reasonActStep` 中模型调用先结束、工具才执行,
没有横跨两者的 stage span,工具 span 就无法归属到发起它的推理阶段。
- **传播需要两处边缘改动**(hook 抽象本身给不了):① `agent.Agent.Interact`
增加 `ctx` 参数——现签名不收 ctx,goroutine 根在 `context.Background()`,
入站 `traceparent` 无路可走;只传播 SpanContext、不传播取消信号,保持与
SSE 生命周期解耦(不影响 #1502)。② MCP 客户端 `sendRequest` 注入 `traceparent`。
- 内容采集受 `capture_content: none|truncated|full` 策略约束(默认 truncated),
OTLP 鉴权只走环境变量;采样用 `ParentBased(TraceIDRatioBased)`。
- 生命周期:`*End` 事件一律 defer 保证(覆盖提前返回与 observe 超时 fallback 路径);
交互 goroutine 增加 recover(现状 panic 会崩进程);`hooks.Stop()` 负责
`ForceFlush`,保证关闭不丢 span。
- TracerProvider 由 hooks 组件唯一拥有;不依赖 Genkit 内部 span 的拓扑
(跨版本不稳定),Genkit span 共享同一 TP 作为补充。
## 范围与拆分
- **hook 核心**:事件模型 + HookManager + 组件装配 + 接口变更
(`Interact`/`NewReActAgent`/`runLoop`)+ 切入点埋事件 + LoggingHook。
验收:各场景(无工具/多工具/降级/超时 fallback/panic)的精确事件序列单测、
并发隔离测试、开销基准(hooks 关闭时热路径仅 nil 判断)。
- **TracingHook**:span 层级 + GenAI 语义约定 + OTLP 导出 +
入站提取/出站注入 + trace id 回传前端 + flush 契约。
验收:Jaeger(docker-compose,可进可选 CI)与 Langfuse(文档化手动步骤)
各一次端到端验证。
- **后续补充**:拦截型护栏、Prometheus 指标 hook、`ToolRetry` 事件。
延后项:用户身份属性(等 #1503)、应用内多 exporter(双后端推荐走 Collector)。
--
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]
