@agentunion/kite 1.5.0 → 1.6.1

package/docs//351/223/276/350/267/257/350/277/275/350/270/252/346/226/271/346/241/210.md

@@ -0,0 +1,242 @@
+# 链路追踪方案
+
+## 1 问题与目标
+
+Kite 框架已具备单跳追踪能力（`event_id`、`rpc_id`、`session_id` + `seq`），但缺少贯穿完整调用链的统一标识。当一次用户操作触发多跳 RPC（如 Web → Kernel → model_service → watchdog），无法将这些独立的 RPC 调用串联为一条链路。
+
+**目标**：引入 `trace_id`，使一次完整操作的所有 RPC 调用和事件可被统一追踪。
+
+## 2 设计原则
+
+| 原则 | 说明 |
+|------|------|
+| 模块零改动 | trace 上下文由 Kernel 自动注入和传播，模块无需感知 |
+| 协议兼容 | `_trace` 是 JSON-RPC 2.0 `params` 内的普通字段，与现有 `_caller_id` 惯例一致 |
+| 零外部依赖 | 不依赖 OpenTelemetry 等外部库，纯 Python 标准库实现 |
+| 跨语言透明 | `_trace` 是 JSON 字段，Python/Node.js/Binary 模块均可读取 |
+
+## 3 trace 上下文结构
+
+Kernel 在转发 RPC 时，向 `params` 注入 `_trace` 字段：
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "fwd-abc123",
+  "method": "get_status",
+  "params": {
+    "_caller_id": "web",
+    "_trace": {
+      "trace_id": "550e8400-e29b-41d4-a716-446655440000",
+      "parent_rpc_id": "fwd-def456",
+      "origin": "web",
+      "depth": 2
+    },
+    "verbose": true
+  }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `trace_id` | UUID string | 一次完整操作的唯一标识，链路入口生成，全程不变 |
+| `parent_rpc_id` | string | 上一跳的 `rpc_id`（`fwd-xxx`），首跳为 `null` |
+| `origin` | string | 链路发起者模块 ID |
+| `depth` | int | 调用深度，从 1 开始递增，用于防止无限递归 |
+
+## 4 传播规则
+
+### 4.1 新链路（入站请求无 `_trace`）
+
+模块 A 调用 `watchdog.get_status`，params 中无 `_trace`：
+
+1. Kernel 生成新 `trace_id`（UUID）
+2. 设置 `parent_rpc_id = null`，`origin = caller_id`，`depth = 1`
+3. 注入 `_trace` 到转发的 params
+
+### 4.2 继承链路（入站请求有 `_trace`）
+
+模块 B 在处理某个 RPC 的过程中，又调用了 `watchdog.report`，并在 params 中携带了从上游收到的 `_trace`：
+
+1. Kernel 继承上游的 `trace_id`（不变）
+2. 设置 `parent_rpc_id` = 当前跳的 `rpc_id`
+3. `depth += 1`
+4. `origin` 保持不变
+
+### 4.3 深度保护
+
+`depth` 超过 **20** 时，Kernel 拒绝转发并返回错误码 `-32007`（TRACE_DEPTH_EXCEEDED），防止无限递归调用链。
+
+## 5 rpc.call.completed 事件增强
+
+现有事件 `data` 新增 `trace_id` 字段：
+
+```json
+{
+  "event": "rpc.call.completed",
+  "data": {
+    "rpc_id": "fwd-abc123",
+    "trace_id": "550e8400-...",
+    "caller": "web",
+    "target": "watchdog",
+    "method": "watchdog.get_status",
+    "duration": 123.45,
+    "status": "success",
+    "parent_rpc_id": null,
+    "depth": 1
+  }
+}
+```
+
+新增字段：`trace_id`、`parent_rpc_id`、`depth`。
+
+## 6 内存缓存
+
+Kernel 在 `RpcRouter` 中维护一个内存 trace 缓存：
+
+- **数据结构**：`dict[trace_id → list[TraceSpan]]`
+- **TTL**：5 分钟，超时自动清理
+- **清理机制**：每次写入时检查并淘汰过期条目
+- **容量上限**：最多保留 1000 条 trace（FIFO 淘汰最早的）
+
+`TraceSpan` 包含：`rpc_id`、`caller`、`target`、`method`、`duration`、`status`、`error`、`parent_rpc_id`、`depth`、`timestamp`。
+
+## 7 查询接口
+
+新增 Kernel 内置 RPC 方法：
+
+### `trace.query`
+
+查询内存缓存中的 trace 记录。
+
+**请求**：
+
+```json
+{
+  "method": "trace.query",
+  "params": {
+    "trace_id": "550e8400-..."
+  }
+}
+```
+
+**响应**：
+
+```json
+{
+  "result": {
+    "trace_id": "550e8400-...",
+    "origin": "web",
+    "span_count": 3,
+    "total_duration_ms": 3945.67,
+    "spans": [
+      {
+        "rpc_id": "fwd-abc123",
+        "caller": "web",
+        "target": "kernel",
+        "method": "kernel.dispatch",
+        "duration": 12.3,
+        "status": "success",
+        "parent_rpc_id": null,
+        "depth": 1,
+        "timestamp": "2026-03-18T10:00:00.123Z"
+      },
+      {
+        "rpc_id": "fwd-def456",
+        "caller": "kernel",
+        "target": "model_service",
+        "method": "model_service.chat",
+        "duration": 3800.0,
+        "status": "success",
+        "parent_rpc_id": "fwd-abc123",
+        "depth": 2,
+        "timestamp": "2026-03-18T10:00:00.135Z"
+      }
+    ]
+  }
+}
+```
+
+### `trace.list`
+
+列出最近的 trace 记录摘要（用于诊断面板）。
+
+**请求**：
+
+```json
+{
+  "method": "trace.list",
+  "params": {
+    "limit": 20
+  }
+}
+```
+
+**响应**：
+
+```json
+{
+  "result": {
+    "traces": [
+      {
+        "trace_id": "550e8400-...",
+        "origin": "web",
+        "span_count": 3,
+        "total_duration_ms": 3945.67,
+        "has_error": false,
+        "started_at": "2026-03-18T10:00:00.123Z"
+      }
+    ],
+    "total": 42
+  }
+}
+```
+
+## 8 故障诊断流程
+
+```
+步骤 1：发现问题
+  前端报错 / 用户反馈 / 监控告警
+
+步骤 2：获取 trace_id
+  → 前端：从 RPC 错误响应中提取
+  → 日志：grep trace_id 在模块 latest.log 中
+
+步骤 3：查询完整链路
+  → 实时（5 分钟内）：调用 trace.query(trace_id)
+  → 历史：grep trace_id 在 Logs 模块持久化文件中
+
+步骤 4：定位瓶颈
+  按 spans 的 duration 和 status 排序，找到耗时最长或失败的跳
+
+步骤 5：深入模块日志
+  根据定位到的 target 模块，查看 {module}/log/latest.log
+```
+
+## 9 职责分工
+
+| 角色 | 职责 |
+|------|------|
+| **Kernel RpcRouter** | 生成 trace_id、注入 `_trace`、传播上下文、内存缓存、`trace.query`/`trace.list` |
+| **rpc.call.completed 事件** | 携带 trace_id，供任何订阅者消费 |
+| **Logs 模块**（未来） | 订阅事件持久化，提供历史查询 |
+| **Audit 模块**（未来） | 按需将 trace_id 关联到审计记录 |
+| **kite_console 前端**（未来） | 可视化调用链 |
+
+## 10 错误码
+
+| 代码 | 常量 | 含义 |
+|------|------|------|
+| -32007 | `TRACE_DEPTH_EXCEEDED` | trace 调用深度超过 20，疑似递归 |
+
+## 11 改动清单
+
+| 文件 | 改动 |
+|------|------|
+| `kernel/rpc_router.py` | PendingForward 增加 trace_id；_forward() 注入/传播 _trace；_publish_rpc_event() 增加 trace 字段；内存缓存；trace.query/trace.list 方法 |
+
+## 12 兼容性
+
+- **向后兼容**：`_trace` 是 params 内的可选字段，现有模块无需任何修改
+- **与 `_caller_id` 共存**：两者并行存在，`_caller_id` 标识直接调用者，`trace_id` 标识完整链路
+- **跨语言**：纯 JSON 字段，任何语言的模块都可以读取（也可以忽略）