fuzhengwei / fuzhengwei/WaLiAPI
数据面 X-Request-Id 标准化(兼容 Wali-Trace-Id)+ OTLP/HTTP JSON 日志导出器
- Dominant language
- Rust
- Stars
- 128
- Forks
- 39
- Avg merge
- 15h 25m
- Merged PRs (30d)
- 44
Description
### 现状(如实声明)
网关**已有** `Wali-Trace-Id` 请求头 → `request_logs.trace_id` 列的关联键机制,但存在四个缺口:
1. 头名是自定义的,业界标准 `X-Request-Id` 不被采纳;
2. 仅 chat / responses / embeddings 三端点读取——messages / count_tokens 未接(trace 恒 None);
3. 客户端不带头时无值生成;
4. 响应不回显。
另外 request_log 原始数据(tokens/时长/渠道/协议/缓存命中)齐备但**没有任何导出器**,无法接入 Langfuse/Helicone 等观测体系。
### 方案
**关联键标准化**:
- 数据面最外层中间件:`X-Request-Id` 优先 → `Wali-Trace-Id` 兼容回退 → 缺省生成 UUIDv4;解析结果回写请求头(handler 侧共享同一 resolve,两级解析天然一致),响应头回显 `X-Request-Id`。
- 非法值(空 / 超 128 字符 / 含空格控制符 / 非 ASCII)视为未携带——防头注入。
- messages 与 count_tokens 补接(此前恒 None);messages 全部落账路径(原生流 finalizer 499/502、原生非流、codec 转换、451 阻断)携带 trace_id 落库。
- **复用既有 trace_id 列,零迁移**;关联键不受日志明细级别策略剥离。
**OTLP 导出器**:
- 后台循环按 **seq 游标**增量读 request_log → 映射 OTLP/HTTP JSON span(SERVER kind、起止时间用 `started_at` 回退 `created_at`、属性含 model/upstream_model/tokens×4/duration/status/is_stream/is_retry/channel/api_key)→ POST 用户配置端点。
- **不引 opentelemetry SDK**——OTLP/HTTP JSON 是稳定的 protobuf-JSON 映射,既有 HTTP 客户端直发即可,避免为旁路功能引入全家桶依赖。
- 游标持久化于设置存储(断点续传);导出失败游标不推进(at-least-once),traceId/spanId 由行 id 确定性派生,接收端可幂等去重;指数退避封顶 10 分钟;**默认关闭,关闭时零后台流量**;鉴权头从设置存储读取。
- 桌面与 headless 两处挂接;设置页新增 OTLP 导出区。
### 测试
sanitize/resolve 纯函数 7 例;router 中间件回显 4 例 + **关联键闭环端到端**(本地 mock 上游全链:响应头回显值 == 落库 trace_id);OTLP span 映射 + mock OTLP 端点集成(发送结构/游标推进/无新行零发送/失败游标保持)6 例。
### 开放点
1. 若维护者倾向官方 opentelemetry SDK,可回退讨论(当前取舍:旁路功能不值得全家桶依赖);
2. span 属性集是否需要增删(如 T09 的 route_group / provider 等观测列);
3. Langfuse 对接示例文档是否随 PR 附带。
---
对应分支:`feat/capability-c05-request-id-otlp`(无迁移)。
Contributor guide
No contributing guide indexed for this repository
Research direction
No file paths are named. Start by locating the data-plane router middleware, request_log persistence, desktop and headless lifecycle hooks, and settings UI, then review the proposed sanitize/resolve, router end-to-end, and OTLP integration tests. Done means the request-id paths and export behavior match the listed cases, including cursor handling and disabled-export behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, rust, tauri
- Domain
- backend-api-design, databases, desktop, observability, testing-qa
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100