fuzhengwei / fuzhengwei/WaLiAPI

数据面 X-Request-Id 标准化(兼容 Wali-Trace-Id)+ OTLP/HTTP JSON 日志导出器

Open
#85 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.