refactor: replace operation trace with telemetry
fix telemetry demo skill ingestion
simplify telemetry summary metric keys
rename remaining trace telemetry artifacts
feat: support configurable telemetry payloads
docs: rewrite operation telemetry design in chinese
fix: reject telemetry for async session commit
refactor: isolate telemetry orchestration
refactor: remove telemetry from find payloads
refactor: remove telemetry event payloads
fix(trace): keep only telemetry-related changes
fix(trace): remove top-level usage from telemetry responses
feat(console): default telemetry on proxied operations
操作级 Telemetry 设计
1. 背景与目标
OpenViking 需要一套统一的 telemetry 机制,用来描述一次操作在执行过程中的关键观测信息。当前已经落地的是操作级 telemetry,主要覆盖:
这里统一使用
telemetry,而不是trace,原因是这套抽象未来不只服务于“单次操作链路”,还要能承载非操作级数据,例如:当前实现只对“操作级 telemetry”提供正式接口,但抽象命名和结构已经为后续扩展预留空间。
2. 设计原则
2.1 详细信息显式按需返回
详细 telemetry 由调用方通过
telemetry参数显式请求,当前对外协议只返回结构化 summary,不返回事件流。2.3 字段名直接面向用户
内部打点名与对外 summary 字段名保持一致,避免额外的“内部名 -> 外部名”转换层。
2.4 缺失分组不返回
如果某类操作天然不会产出某个 summary 分组,则该分组直接省略,不返回空对象或全
null字段。例如:
resources.add_resource不一定有memorysession.commit一般没有semantic_nodesvector3. 当前支持范围
3.1 HTTP 接口
当前已接入 operation telemetry 的接口:
POST /api/v1/search/findPOST /api/v1/search/searchPOST /api/v1/resourcesPOST /api/v1/skillsPOST /api/v1/sessions/{session_id}/commit说明:
session.commit仅在wait=true的同步模式下支持返回 telemetrywait=false的异步任务模式当前不支持 telemetry,请求时会返回INVALID_ARGUMENT3.2 SDK 接口
当前已接入 operation telemetry 的 SDK 方法:
add_resourceadd_skillfindsearchcommit_session本地嵌入式 client 和 HTTP client 都遵循同一套 telemetry 请求语义。
4. 响应模型
服务端仍使用统一响应包裹结构:
{ "status": "ok", "result": { "...": "..." }, "time": 0.031, "telemetry": { "id": "tm_9f6f4d6b0d0c4f4d93ce5adf82e71c18", "summary": { "operation": "search.find", "status": "ok", "duration_ms": 31.224, "tokens": { "total": 24, "llm": { "input": 12, "output": 6, "total": 18 }, "embedding": { "total": 6 } }, "vector": { "searches": 3, "scored": 26, "passed": 8, "returned": 5, "scanned": 26, "scan_reason": "" } } } }说明:
telemetry只在调用方显式请求时返回telemetry.id是不透明标识,只用于关联,不要求调用方解析语义5. telemetry 请求语义
telemetry字段支持两种形态:5.1 布尔形态
{ "telemetry": true }语义:
telemetry.id + telemetry.summary5.2 对象形态
{ "telemetry": { "summary": true } }语义:
summary默认值为true当前支持的合法组合如下:
falsetelemetrytrueid + summary{"summary": true}id + summary{"summary": false}telemetry以下请求非法:
{ "telemetry": { "events": true } }原因是当前对外 telemetry 已收敛为 summary-only,不再接受事件流选择参数。
6. telemetry 的职责划分
6.1
telemetry.summarysummary是结构化的操作摘要,用于:当前 summary 的核心字段包括:
operationstatusduration_mstokensqueuevectorsemantic_nodesmemoryerrors其中:
tokens始终存在6.3
telemetry.idtelemetry.id是请求级关联标识,用于把一次操作的 summary 与内部异步链路统计关联起来。7. summary 字段约定
7.1 顶层公共字段
所有 summary 至少包含:
operationstatusduration_mstokens7.2 tokens
示例:
{ "tokens": { "total": 19, "llm": { "input": 11, "output": 7, "total": 18 }, "embedding": { "total": 1 } } }说明:
llm统计输入、输出与总量embedding当前只统计总量7.3 queue
队列相关摘要示例:
{ "queue": { "semantic": { "processed": 1, "error_count": 0 }, "embedding": { "processed": 1, "error_count": 0 } } }7.4 vector
向量检索摘要示例:
{ "vector": { "searches": 2, "scored": 5, "passed": 3, "returned": 2, "scanned": 5, "scan_reason": "" } }7.5 semantic_nodes
语义检索 DAG / 节点级摘要示例:
{ "semantic_nodes": { "total": 4, "done": 3, "pending": 1, "running": 0 } }7.6 memory
会话提交等内存提取类操作示例:
{ "memory": { "extracted": 4 } }7.7 errors
发生错误时可返回:
{ "errors": { "stage": "resource_processor.parse", "error_code": "PROCESSING_ERROR", "message": "..." } }无错误时,该分组可以省略。
8. 缺失字段裁剪策略
summary 采用“按分组裁剪”的策略,而不是固定返回整套字段。
这样做有几个直接收益:
示例:
8.1
resources.add_resource可能返回:
{ "operation": "resources.add_resource", "status": "ok", "duration_ms": 152.3, "tokens": { "...": "..." }, "semantic_nodes": { "...": "..." }, "queue": { "...": "..." } }这里不应强行返回
memory。8.2
session.commit可能返回:
{ "operation": "session.commit", "status": "ok", "duration_ms": 48.1, "tokens": { "...": "..." }, "memory": { "extracted": 4 } }这里不应强行返回
semantic_nodes。9. 成本模型
当前 collector 只采集 summary 所需的数据:
10. 实现结构
10.1 核心类型
核心实现位于:
openviking/telemetry/operation.pyopenviking/telemetry/request.pyopenviking/telemetry/context.pyopenviking/telemetry/registry.py主要对象包括:
OperationTelemetryTelemetrySnapshotTelemetrySelection10.2 请求解析
openviking/telemetry/request.py负责统一解析telemetry请求参数:bool | objectTelemetrySelectionevents这样 server、local client、HTTP client 都共享同一套语义。
10.3 服务端集成
openviking/server/telemetry.py负责:summaryrouter 层的职责是:
telemetry10.4 本地与 HTTP client
本地 client 和 HTTP client 都暴露同样的
telemetry参数语义:其中:
11. 异步链路与跨组件聚合
当前 operation telemetry 不只覆盖同步请求栈,也支持部分异步处理链路的数据回流。
典型场景包括:
实现方式是:
telemetry.idid这样一次操作的最终 summary 可以覆盖:
12. 与 OpenTelemetry 的关系
当前方案不是直接把 OpenTelemetry 暴露为业务接口,而是先定义 OpenViking 自己的 telemetry 抽象。
这样做的好处是:
可以把 OpenTelemetry 看作未来的一种底层实现或导出方式,而不是当前对外协议本身。
13. 未来扩展方向
当前文档描述的是 operation telemetry,但未来需要兼容更广义的 telemetry 数据源。
推荐的扩展方向:
这些扩展不要求沿用完全相同的 summary schema,但应复用统一的 telemetry 抽象和运行时。
14. 使用示例
14.1 返回 telemetry summary
14.2 只返回 summary
14.4 Python SDK
15. 新接口接入规范
新接口如果需要接入 operation telemetry,建议遵循以下规则:
OperationTelemetrycollector。telemetry。这样可以保持默认低成本,同时为调用方提供稳定、可分析的结构化摘要。