fuzhengwei / fuzhengwei/WaLiAPI

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

Open
#80 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

Locate the data-plane router middleware, request_log persistence, settings storage, desktop and headless startup hooks, and settings page; begin by tracing the existing Wali-Trace-Id handling. Use the specified sanitize/resolve, router echo, end-to-end, and OTLP mock integration tests as the acceptance map. Done means standardized IDs reach responses and logs, OTLP export resumes safely, and disabled or empty export performs no sends.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api, backend, desktop, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.