From 0be111d64cdcdfc37021f5ca11f96b6d1f2f1e5d Mon Sep 17 00:00:00 2001 From: iomgaa Date: Mon, 20 Jul 2026 07:12:27 -0400 Subject: [PATCH] docs: register llm_calls telemetry schema in wiki --- research-wiki/graph/edges.json | 24 +++++++++++++ research-wiki/index.md | 8 ++++- research-wiki/log.md | 5 +++ .../metrics/call-telemetry-coverage.md | 9 +++++ research-wiki/schemas/llm-calls.md | 36 +++++++++++++++++++ 5 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 research-wiki/metrics/call-telemetry-coverage.md create mode 100644 research-wiki/schemas/llm-calls.md diff --git a/research-wiki/graph/edges.json b/research-wiki/graph/edges.json index 818ed4f..00bc1c4 100644 --- a/research-wiki/graph/edges.json +++ b/research-wiki/graph/edges.json @@ -5,6 +5,16 @@ "id": "plan:m1-core-plan", "label": "M1 核心里程碑实现计划", "type": "plan" + }, + { + "id": "schema:llm-calls", + "label": "表结构: llm_calls(遥测 18 字段)", + "type": "schema" + }, + { + "id": "metric:call-telemetry-coverage", + "label": "每次调用必录覆盖率(含缓存命中/失败/取消)", + "type": "metric" } ], "links": [ @@ -14,6 +24,20 @@ "relation": "implements", "evidence": "plans/2026-07-20-m1-core-plan.md 实现 designs/2026-07-20-m1-core-design.md 冻结的全部签名", "added": "2026-07-20T10:18:41.339537+00:00" + }, + { + "source": "metric:call-telemetry-coverage", + "target": "schema:llm-calls", + "relation": "measures", + "evidence": "遥测必录铁律: 一切调用路径落 llm_calls", + "added": "2026-07-20T11:11:46.302045+00:00" + }, + { + "source": "schema:llm-calls", + "target": "design:m1-core-design", + "relation": "implements", + "evidence": "M1 设计 §4.4 冻结 18 字段", + "added": "2026-07-20T11:11:47.240466+00:00" } ] } \ No newline at end of file diff --git a/research-wiki/index.md b/research-wiki/index.md index 351c63a..7cbe81c 100644 --- a/research-wiki/index.md +++ b/research-wiki/index.md @@ -1,6 +1,6 @@ # Research Wiki 索引 -> 自动生成，更新时间：2026-07-20 10:18 UTC +> 自动生成，更新时间：2026-07-20 11:11 UTC ## design (2) - [2026-07-20-m1-core-design](designs/2026-07-20-m1-core-design.md) `design:2026-07-20-m1-core-design` @@ -9,3 +9,9 @@ ## plan (2) - [2026-07-20-m1-core-plan](plans/2026-07-20-m1-core-plan.md) `plan:2026-07-20-m1-core-plan` - [M1 核心里程碑实现计划](plans/m1-core-plan.md) `plan:m1-core-plan` + +## schema (1) +- [表结构: llm_calls(遥测 18 字段)](schemas/llm-calls.md) `schema:llm-calls` + +## metric (1) +- [每次调用必录覆盖率(含缓存命中/失败/取消)](metrics/call-telemetry-coverage.md) `metric:call-telemetry-coverage` diff --git a/research-wiki/log.md b/research-wiki/log.md index f21a688..f946ea2 100644 --- a/research-wiki/log.md +++ b/research-wiki/log.md @@ -5,3 +5,8 @@ - [2026-07-20 10:18 UTC] 新增 plan: M1 核心里程碑实现计划 (plan:m1-core-plan) - [2026-07-20 10:18 UTC] 新增边: plan:m1-core-plan --implements--> design:m1-core-design - [2026-07-20 10:18 UTC] 重建索引: 4 篇页面 +- [2026-07-20 11:11 UTC] 新增 schema: 表结构: llm_calls(遥测 18 字段) (schema:llm-calls) +- [2026-07-20 11:11 UTC] 新增 metric: 每次调用必录覆盖率(含缓存命中/失败/取消) (metric:call-telemetry-coverage) +- [2026-07-20 11:11 UTC] 新增边: metric:call-telemetry-coverage --measures--> schema:llm-calls +- [2026-07-20 11:11 UTC] 新增边: schema:llm-calls --implements--> design:m1-core-design +- [2026-07-20 11:11 UTC] 重建索引: 6 篇页面 diff --git a/research-wiki/metrics/call-telemetry-coverage.md b/research-wiki/metrics/call-telemetry-coverage.md new file mode 100644 index 0000000..19ffabf --- /dev/null +++ b/research-wiki/metrics/call-telemetry-coverage.md @@ -0,0 +1,9 @@ +--- +type: metric +node_id: metric:call-telemetry-coverage +title: 每次调用必录覆盖率(含缓存命中/失败/取消) +date: 2026-07-20 +--- + +# 每次调用必录覆盖率(含缓存命中/失败/取消) + diff --git a/research-wiki/schemas/llm-calls.md b/research-wiki/schemas/llm-calls.md new file mode 100644 index 0000000..831c8b6 --- /dev/null +++ b/research-wiki/schemas/llm-calls.md @@ -0,0 +1,36 @@ +--- +type: schema +node_id: schema:llm-calls +title: "表结构: llm_calls(遥测 18 字段)" +date: 2026-07-20 +--- + +# 表结构: llm_calls(遥测 18 字段) + + +## 列定义(冻结,M1 设计 §4.4 / ARCH §7.8) + +| 列 | 类型 | 说明 | +|---|---|---| +| call_id | TEXT PRIMARY KEY | 每次尝试独立 UUID;INSERT OR IGNORE 幂等 | +| parent_call_id / session_id | TEXT | 调用链路(agent step → LLM call) | +| model / provider / source_name | TEXT NOT NULL | 溯源;model 由旧 Protocol 的 model_name 更名(VT 迁移 §8) | +| messages / response / thinking | TEXT NOT NULL | messages 落库前多模态 part 摘要(与缓存 key 共用 digest_messages) | +| prompt_tokens / completion_tokens | INTEGER NOT NULL | usage 帧;缺失按 est 兜底 | +| usage_source | TEXT NOT NULL | measured / estimated | +| latency_ms | INTEGER NOT NULL | 尝试耗时;缓存命中 0 | +| ttft_ms / max_inter_token_ms | REAL | 流式活性测量 | +| cache_hit | INTEGER NOT NULL DEFAULT 0 | 命中标记 | +| error | TEXT | 异常信息;取消记 "cancelled" | +| cost | REAL | M1 恒 NULL,M2 pricing 换算 | +| created_at | TEXT NOT NULL DEFAULT (datetime('now')) | 落库时刻 | + +## 埋点位置(单一 helper 铁律) + +- `middleware/telemetry.py::TelemetryEmitter` 是全库**唯一** `record_llm_call` 调用点; +- `TelemetryMW`(最外层)记缓存命中与最终失败;`RetryMW._emit` 经同一 Emitter 逐次记尝试; +- 写失败降级 warning 不冒泡;取消路径 finally 尽力记录。 + +## 评估基线 + +首版无历史基线,标"待首次运行后建立";验收断言: 单测覆盖成功/失败/缓存命中/取消四路径各产生恰一行;并发 50 协程写全落库。