feat: add stall_ms and stall_count telemetry columns
Third approved port change: TelemetryRecorder.record_llm_call gains stall_ms/stall_count (assembly gate derives from this signature). Schema five edit points (both DDLs, both backfill decls, COLUMNS) with INTEGER nullable columns appended last; telemetry_schema_sql regenerates from the same constants untouched. Emitter forwards the pair from retry._emit on the success branch only (cancelled hedge loser rows stay NULL by construction); cache-hit and terminal rows pass explicit None. Both **fields recorders pick the columns up with zero signature change.
This commit is contained in:
@@ -216,6 +216,11 @@ class _AttemptUsage:
|
||||
# 内部字段用枚举类型;裸 str 归一化只发生在 `_record` 下沉 recorder 那一步。
|
||||
# 失败尝试无响应可言,默认 UNKNOWN 本身就是事实("观测不到"),不撒谎
|
||||
thinking_observation: ThinkingObservation = ThinkingObservation.UNKNOWN
|
||||
# 1.3.8(issue #27): stall 归因**不从 response 取**——LLMResponse 不增顶层
|
||||
# 字段(设计 §11-B2 裁决 b),stall 由 retry 层经 emit_attempt 显式 kw 传入;
|
||||
# 两字段留在此处只为让"尝试视图"形状完整,默认 None 即"无沉默观测"
|
||||
stall_ms: int | None = None
|
||||
stall_count: int | None = None
|
||||
|
||||
@classmethod
|
||||
def of(cls, response: LLMResponse | None) -> _AttemptUsage:
|
||||
@@ -365,7 +370,7 @@ def _assert_recorder_shape(recorder: TelemetryRecorder) -> None:
|
||||
|
||||
|
||||
class TelemetryEmitter:
|
||||
"""从请求与结果组装 36 字段并写入 recorder;一切写失败降级 warning。"""
|
||||
"""从请求与结果组装 38 字段并写入 recorder;一切写失败降级 warning。"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
@@ -405,6 +410,12 @@ class TelemetryEmitter:
|
||||
reasoning_applies: bool,
|
||||
operation: CallOperation,
|
||||
class_prefixed_error: bool = False,
|
||||
# 1.3.8(issue #27): 沉默归因由调用点显式传入(成功分支从 TransportResult
|
||||
# 换算;失败/取消分支不传)。**默认 None 语义安全**: 漏传落 NULL 是合法事实
|
||||
# ("非流式/无沉默观测"),不是"没表态"——与 reasoning_applies 不同类;
|
||||
# 默认保住约 50 处既有调用点零改动(计划 §3.4 取舍)
|
||||
stall_ms: int | None = None,
|
||||
stall_count: int | None = None,
|
||||
) -> None:
|
||||
"""逐次尝试记录(三个 Client 的重试层调用);失败尝试无用量可言,记 0 并标 unavailable。
|
||||
|
||||
@@ -451,6 +462,8 @@ class TelemetryEmitter:
|
||||
event_kind="attempt",
|
||||
attempts=None,
|
||||
total_latency_ms=None,
|
||||
stall_ms=stall_ms,
|
||||
stall_count=stall_count,
|
||||
)
|
||||
|
||||
async def emit_cache_hit(
|
||||
@@ -498,6 +511,9 @@ class TelemetryEmitter:
|
||||
event_kind="cache_hit",
|
||||
attempts=None,
|
||||
total_latency_ms=None,
|
||||
# 缓存命中行未产生 transport 观测: 无沉默可言,显式 None
|
||||
stall_ms=None,
|
||||
stall_count=None,
|
||||
)
|
||||
|
||||
async def emit_terminal_failure(
|
||||
@@ -550,6 +566,9 @@ class TelemetryEmitter:
|
||||
event_kind="terminal_failure",
|
||||
attempts=stats.attempts,
|
||||
total_latency_ms=stats.total_latency_ms,
|
||||
# 终态行无具体源与 transport 观测: 显式 None
|
||||
stall_ms=None,
|
||||
stall_count=None,
|
||||
)
|
||||
|
||||
async def _record(
|
||||
@@ -592,6 +611,10 @@ class TelemetryEmitter:
|
||||
event_kind: EventKind,
|
||||
attempts: int | None,
|
||||
total_latency_ms: int | None,
|
||||
# —— 1.3.8: 沉默归因两列(issue #27);各入口已按自己的事实定型,
|
||||
# 本方法只搬运(同 reasoning_effort 先例)——
|
||||
stall_ms: int | None,
|
||||
stall_count: int | None,
|
||||
) -> None:
|
||||
try:
|
||||
# 成本换算(M2 §6): 成功行按单价换算;缓存命中 0.0(未产生新调用);
|
||||
@@ -660,6 +683,8 @@ class TelemetryEmitter:
|
||||
error_body=errors.error_body,
|
||||
attempts=attempts,
|
||||
total_latency_ms=total_latency_ms,
|
||||
stall_ms=stall_ms,
|
||||
stall_count=stall_count,
|
||||
)
|
||||
except asyncio.CancelledError:
|
||||
raise
|
||||
|
||||
@@ -284,7 +284,7 @@ class TelemetryStatusProvider(Protocol):
|
||||
|
||||
@runtime_checkable
|
||||
class TelemetryRecorder(Protocol):
|
||||
"""遥测后端;36 字段冻结(M1 设计 §4.4 + issue #3/#4/#11/#16/#20 + 1.3.5),唯一调用点是 TelemetryEmitter。
|
||||
"""遥测后端;38 字段冻结(M1 设计 §4.4 + issue #3/#4/#11/#16/#20 + 1.3.5/1.3.8),唯一调用点是 TelemetryEmitter。
|
||||
|
||||
新增参数不设默认值: 库外无第三方实现者(三项目迁移时删除了各自的同名
|
||||
Protocol),完整签名的成本为零,而少写一列会被 emitter 的降级吞成 warning。
|
||||
@@ -349,4 +349,6 @@ class TelemetryRecorder(Protocol):
|
||||
error_body: str | None,
|
||||
attempts: int | None,
|
||||
total_latency_ms: int | None,
|
||||
stall_ms: int | None,
|
||||
stall_count: int | None,
|
||||
) -> None: ...
|
||||
|
||||
@@ -5,8 +5,8 @@
|
||||
多处各存一份必然漂移,而漂移的表现是"下游照打印的 SQL 建完表,库仍报缺列"。
|
||||
|
||||
**`COLUMNS` 是 INSERT 字段序,不是物理列序**: 数据库自填的 `created_at` 不在其中(它带
|
||||
`DEFAULT now()` / `datetime('now')`,库从不显式写它)。物理表列 = 36 个 INSERT 字段 +
|
||||
`created_at` = 37;列数断言一律按物理列数写,两套口径混用是最易错处。
|
||||
`DEFAULT now()` / `datetime('now')`,库从不显式写它)。物理表列 = 38 个 INSERT 字段 +
|
||||
`created_at` = 39;列数断言一律按物理列数写,两套口径混用是最易错处。
|
||||
|
||||
本模块只依赖标准库: `telemetry/` 与 `backends/`、`transports/`、`structured/` 同层且
|
||||
互不依赖(import-linter 契约执法)。
|
||||
@@ -62,7 +62,9 @@ CREATE TABLE IF NOT EXISTS llm_calls (
|
||||
cause_type TEXT,
|
||||
error_body TEXT,
|
||||
attempts INTEGER,
|
||||
total_latency_ms INTEGER
|
||||
total_latency_ms INTEGER,
|
||||
stall_ms INTEGER,
|
||||
stall_count INTEGER
|
||||
);
|
||||
"""
|
||||
|
||||
@@ -104,7 +106,9 @@ CREATE TABLE IF NOT EXISTS llm_calls (
|
||||
cause_type TEXT,
|
||||
error_body TEXT,
|
||||
attempts INTEGER,
|
||||
total_latency_ms INTEGER
|
||||
total_latency_ms INTEGER,
|
||||
stall_ms INTEGER,
|
||||
stall_count INTEGER
|
||||
);
|
||||
"""
|
||||
|
||||
@@ -137,6 +141,10 @@ SQLITE_BACKFILL = (
|
||||
("error_body", "TEXT"),
|
||||
("attempts", "INTEGER"),
|
||||
("total_latency_ms", "INTEGER"),
|
||||
# 1.3.8 沉默归因两列(issue #27): 同样可空无默认——旧行 NULL = "补列之前
|
||||
# 没记过这件事",与"观测过且零沉默"(0)是两回事
|
||||
("stall_ms", "INTEGER"),
|
||||
("stall_count", "INTEGER"),
|
||||
)
|
||||
|
||||
# PG 补列的列定义。语句由此派生成两份文本(见下),使"库内执行的那份"与"打印给
|
||||
@@ -163,6 +171,9 @@ _PG_BACKFILL_DECLS = (
|
||||
("error_body", "TEXT"),
|
||||
("attempts", "INTEGER"),
|
||||
("total_latency_ms", "INTEGER"),
|
||||
# 1.3.8 两列,列序与 SQLITE_BACKFILL 逐项对齐(理由同上)
|
||||
("stall_ms", "INTEGER"),
|
||||
("stall_count", "INTEGER"),
|
||||
)
|
||||
|
||||
# 新列排在 created_at 之后: 与旧表 ALTER 追加的位置一致(见 SQLITE_BACKFILL 同款注释)。
|
||||
@@ -212,6 +223,9 @@ COLUMNS = (
|
||||
"error_body",
|
||||
"attempts",
|
||||
"total_latency_ms",
|
||||
# —— 1.3.8 沉默归因(issue #27)——
|
||||
"stall_ms",
|
||||
"stall_count",
|
||||
)
|
||||
|
||||
_COLUMN_SET = frozenset(COLUMNS)
|
||||
|
||||
@@ -143,7 +143,7 @@ class SQLiteRecorder:
|
||||
logger.warning("SQLite 遥测补列失败(写入将逐行降级): {}", exc)
|
||||
|
||||
async def record_llm_call(self, **fields: object) -> None:
|
||||
"""写一行遥测;字段集合即 36 字段冻结签名(ports.TelemetryRecorder)。
|
||||
"""写一行遥测;字段集合即 38 字段冻结签名(ports.TelemetryRecorder)。
|
||||
|
||||
取值按 `self._columns`(manual 档可能已被裁剪),与 `self._insert` 的
|
||||
占位符同序——两者必须一起改,分开改就是把值写进错位的列。
|
||||
|
||||
Reference in New Issue
Block a user