OpenViking 请求级 Trace 方案设计

[kkkwjx07]

OpenViking 请求级 Trace 详细设计文档

摘要

本设计为 OpenViking 增加请求粒度 trace 能力，覆盖 find / search / add_resource / add_skill / session.commit。
设计重点是把“采集、聚合、输出”解耦成统一框架，业务只上报事件，不拼装响应。
默认关闭，开启后返回稳定的 result.trace（summary + events），并内置版本化与扩展点。

———

1. 设计原则

• 高内聚：trace 逻辑集中在 openviking/trace/，业务层不持有输出协议细节。
• 低耦合：通过 provider/registry 注入指标，接口间互不污染。
• 可扩展：新增接口或指标只需加 provider，不改核心 collector。
• 兼容性：trace=false 行为完全不变；trace=true 仅增加 result.trace。
• 可演进：trace schema 带 schema_version，支持未来增量字段。

———

2. API 变更与用法

请求参数

所有目标接口新增：

• trace: bool = false

接口列表：

• POST /api/v1/search/find
• POST /api/v1/search/search
• POST /api/v1/resources
• POST /api/v1/skills
• POST /api/v1/sessions/{session_id}/commit

使用示例（HTTP）

curl -X POST http://localhost:8080/api/v1/search/find
-H 'Content-Type: application/json'
-d '{
"query": "memory dedup strategy",
"limit": 5,
"trace": true
}'

curl -X POST http://localhost:8080/api/v1/resources
-H 'Content-Type: application/json'
-d '{
"path": "/tmp/a.md",
"wait": true,
"trace": true
}'

Python 用法（建议）

res = await client.find(query="semantic node", trace=True)
print(res.trace["summary"]["total_duration_ms"])

———

3. 输出协议（Trace Schema v1）

顶层结构

result.trace 固定为：

• schema_version
• summary
• events

summary 字段（核心指标）

• trace_id
• operation
• status
• total_duration_ms
• token_usage.input_tokens
• token_usage.output_tokens
• token_usage.total_tokens
• vector.search_calls
• vector.candidates_scored
• vector.candidates_after_threshold
• vector.returned
• vector.vectors_scanned（可选，无法获取时为 null）
• vector.scan_unavailable_reason
• semantic_nodes.total_nodes
• semantic_nodes.done_nodes
• semantic_nodes.pending_nodes
• semantic_nodes.in_progress_nodes
• memory.memories_extracted
• errors.error_stage
• errors.error_code
• errors.message

events 字段（时间线）

每条事件包含：

• stage
• name
• ts_ms
• status
• attrs

———

4. 输出示例

示例 A：find(trace=true)

{
"status": "ok",
"result": {
"resources": [],
"memories": [],
"skills": [],
"total": 0,
"trace": {
"schema_version": "v1",
"summary": {
"trace_id": "tr_4f2d...",
"operation": "search.find",
"status": "ok",
"total_duration_ms": 42.8,
"token_usage": {
"input_tokens": 0,
"output_tokens": 0,
"total_tokens": 0
},
"vector": {
"search_calls": 3,
"candidates_scored": 28,
"candidates_after_threshold": 7,
"returned": 5,
"vectors_scanned": null,
"scan_unavailable_reason": "backend_not_exposed"
},
"semantic_nodes": {
"total_nodes": null,
"done_nodes": null,
"pending_nodes": null,
"in_progress_nodes": null
},
"memory": {
"memories_extracted": null
},
"errors": {
"error_stage": "",
"error_code": "",
"message": ""
}
},
"events": [
{
"stage": "retriever.global_search",
"name": "global_search_done",
"ts_ms": 8.4,
"status": "ok",
"attrs": {
"hits": 3
}
}
]
}
}
}

示例 B：add_resource(wait=true, trace=true)

{
"status": "ok",
"result": {
"status": "success",
"root_uri": "viking://resources/doc",
"trace": {
"schema_version": "v1",
"summary": {
"trace_id": "tr_78b1...",
"operation": "resources.add_resource",
"status": "ok",
"total_duration_ms": 631.2,
"token_usage": {
"input_tokens": 412,
"output_tokens": 166,
"total_tokens": 578
},
"vector": {
"search_calls": 0,
"candidates_scored": 0,
"candidates_after_threshold": 0,
"returned": 0,
"vectors_scanned": null,
"scan_unavailable_reason": ""
},
"semantic_nodes": {
"total_nodes": 31,
"done_nodes": 31,
"pending_nodes": 0,
"in_progress_nodes": 0
},
"memory": {
"memories_extracted": null
},
"errors": {
"error_stage": "",
"error_code": "",
"message": ""
}
},
"events": [
{
"stage": "resource.parse",
"name": "parse_done",
"ts_ms": 121.6,
"status": "ok",
"attrs": {
"warnings_count": 1
}
},
{
"stage": "resource.wait",
"name": "queue_complete",
"ts_ms": 629.9,
"status": "ok",
"attrs": {
"semantic_done_nodes": 31
}
}
]
}
}
}

示例 C：session.commit(trace=true)

{
"status": "ok",
"result": {
"memories_extracted": 4,
"trace": {
"schema_version": "v1",
"summary": {
"operation": "session.commit",
"memory": {
"memories_extracted": 4
}
},
"events": []
}
}
}

———

5. 类设计（核心）

类一：TraceCollector

职责：

• 统一记录 event/counter/timing/gauge/error
• 提供请求内线程安全累加
• 结束时导出原始采集快照

关键方法：

• event(stage, name, attrs=None, status="ok")
• count(key, delta=1)
• timing(key, ms)
• set(key, value)
• set_error(stage, code, message)
• finalize(status) -> TraceSnapshot

类二：TraceSummaryBuilder

职责：

• 把 raw snapshot 归并成 summary 字段
• 做指标口径统一（N/A -> null，缺失向量扫描信息填 reason）

关键方法：

• build(snapshot, operation, duration_ms) -> dict

类三：TraceSerializer

职责：

• 固定输出协议 schema_version + summary + events
• 控制字段白名单与脱敏

关键方法：

• to_result(summary, events) -> dict

类四：TraceContext

职责：

• 使用 contextvars 绑定当前请求 collector
• 提供 get_collector() no-op 回退

关键方法：

• bind(collector)（context manager）
• current() -> TraceCollectorLike

类五：TraceProvider（抽象）

职责：

• 对业务模块做指标适配，保持核心与业务解耦

关键方法：

• on_start(ctx, collector)
• on_success(ctx, result, collector)
• on_error(ctx, err, collector)

实现类：

• SearchTraceProvider
• ResourceTraceProvider
• SkillTraceProvider
• SessionCommitTraceProvider
• TokenUsageProvider
• VectorMetricsProvider
• SemanticDagMetricsProvider

———

6. 关键流程设计

Router 层

• 读 trace 参数
• trace=false 直接走原逻辑
• trace=true：
  • 创建 collector
  • with TraceContext.bind(collector): 调业务
  • 收口时 summary = TraceSummaryBuilder.build(...)
  • 注入 result.trace = TraceSerializer.to_result(summary, events)

Service/Storage 层

• 不感知输出格式
• 只调用 collector 记录阶段事件和指标
• 例如检索流程记录 vector.search_calls 与 candidates_*

add_resource(wait=true) 语义结点

• 从 SemanticDagExecutor.get_stats() 取请求级 DAG 指标
• 强约束：完成返回时 done_nodes == total_nodes

———

7. 扩展机制

• 新接口接入 trace：新增 provider + router 绑定即可
• 新指标加入：在 provider 增采集和 builder 映射，不动 collector 基础接口
• 输出协议升级：schema_version 递增并保持向后兼容
• 可选后续扩展：trace_level=minimal|core|full，由 serializer 控制输出粒度

———

8. 测试与验收

• 兼容性：trace=false 响应与历史一致
• 必填指标：token 三项、total_duration_ms 总是出现
• 请求隔离：并发请求 trace_id 与指标不串
• add_resource(wait=true)：semantic_nodes.done_nodes == semantic_nodes.total_nodes
• commit：memory.memories_extracted 与业务结果一致
• 错误路径：errors.error_stage/error_code/message 正确填充

———

9. 默认行为与约束

• 默认 trace=false
• token 只保留你指定三项：input/output/total
• vectors_scanned 允许 null（底层不暴露时）
• 不返回敏感信息与大文本正文
• memory.memories_extracted 仅 session.commit 为实值，其他接口 null

代码实现：
https://github.com/volcengine/OpenViking/tree/feat/request-trace-metrics

[ZaynJarvis]

需要简单改下 code block format。

看起来 http API 透出 token usage 需要等 trace 支持？
另外看 response 结构，没区分 token 类型 (vlm/embed/rerank)

[kkkwjx07]

请求级的token就放到trace这事里一起做了（接口上可以再考虑下是否依赖开启trace，毕竟trace有一定成本）；如果是整体的token开销，我也有打算搞，不过暂时不在这个设计里。
token 类型这事，区分倒是不难，主要还是看怎么算embed/rerank的token。