docs: correct the stale throughput numbers and wiki state
独立验证发现的 3 处文档欠账:
③ 两处代码内注释还挂着已作废的吞吐估算,`.env.example`/README/
CHANGELOG/ARCHITECTURE 四处早已改成实测口径:
- `config.py` 的 `# 4 条 ≈ 32 行/秒(实测…)` —— "32 行/秒"正是设计
§10 修订 #1 判定"偏乐观一倍"并作废的估算值,却挂着"实测"二字;
- `postgres.py` 的 `pool_max` docstring 写着 `稳态吞吐 ≈ pool_max /
RTT`,正是设计要求下游**不要**用的那个公式。
两处统一为实测值: RTT ≈ 123ms 上 `pool_max=4` 约 15.6 行/秒
(50 行并发批 3.2s)。设计 §8 与计划 T7 里残留的同一公式一并标注作废。
④ 文档写 `acquire(timeout=剩余预算)`,实现传的是完整预算(行为无害,
外层 `asyncio.timeout` 才是真正上界)。**改文档不改代码**: 设计
§3.1、计划 T3、ARCH §7.8 三处对齐,并写明为什么内层不再算剩余量。
⑤ wiki 登记页与正文状态漂移: design 登记页仍写"待人类审"(正文已是
"已实施")、plan 登记页写"正文 326 行"(实际 380)、log.md 末条停在
T0 之前。三处校正,T1-T8 补登记,rebuild_index。
另补一条独立验证在真实 PG 上发现的语义细节: 本地池饱和造成的丢行走
**行级丢弃**,`degraded` 保持 False,只有 `dropped_rows` 增长——只按
`degraded` 配告警的下游会完全看不见这类丢行,而它恰是 `pool_max` 配小
了的唯一信号。README / .env.example / ARCHITECTURE / CHANGELOG 各补一句。
This commit is contained in:
@@ -57,6 +57,8 @@
|
||||
|
||||
- 两个新配置键 `PGW_TELEMETRY_PG_POOL_MAX`(缺省 4,须 ≥ 1)与 `PGW_TELEMETRY_PG_WRITE_TIMEOUT_S`(缺省 5.0,须 > 0)。`GatewaySettings` 相应新增两个**带缺省**的字段——与既有遥测字段的"无默认值必填"不同,因为它们回答的是"库该占多少资源",库对此必须有一个可陈述的表态。`PostgresRecorder` 的 `pool_max` / `write_timeout_s` 是 keyword-only **必填**参数(直接构造 recorder 的调用点需补,不传即 `TypeError`)。
|
||||
- `PostgresRecorder.aclose()` 现在是**有界且终局**的: 走 `asyncio.wait_for` + 超时 `terminate()`(`Pool.close()` 在 in-flight 连接未释放时会无限等,asyncpg 自己的文档就建议加 `wait_for`);关闭后写入短路且**不再复活**——此前关完池后下一次写入会拿 DSN 悄悄自建一个新池,注入外部池的调用方以为自己管着全部连接、实际早已不是。
|
||||
- 降级日志的**级别由是否致命决定**: 配置级致命(DSN 写不对)发 **ERROR**——人配错了、本进程内不会自愈,运维必须看见;其余(后端挂了、权限被收、表被删)发 WARNING——外部状态,冷却到期会自己重试。级别只在 `TelemetryStatusTracker` 一处决定,两个 recorder 共用。
|
||||
- 对账请**同时看 `degraded` 与 `dropped_rows`**: 写入因本地池饱和超出预算被丢时走的是行级丢弃,`degraded` 保持 `False`(后端并没有挂,是本进程并发超了),只有 `dropped_rows` 增长。只按 `degraded` 配告警会完全看不见这一类丢行——而它恰是 `PGW_TELEMETRY_PG_POOL_MAX` 配小了的唯一信号。
|
||||
- SQLite 遥测初始化失败后终于有日志了。此前 `sqlite.py` 初始化失败直接 `return`,连一条 warning 都没有,整个进程零遥测且无任何痕迹。SQLite 侧本版**只做可见性**,不做 lazy 化与冷却重连(它的失败模式在装配期就会暴露,不是"跑到一半悄悄断")。
|
||||
- 写入路径不再用 `async with pool.acquire(...)`。`Pool.release()` 是 shielded 且默认复用 acquire 时记录的 timeout,预算到期时那次释放会正常等到完成——业务路径的真实上界因此是 ≈ 2 × 预算而不是一个预算。改为显式 acquire/release 后,承诺精确为"主写入尝试 ≤ 预算,释放路径独立有界(1s,超时即 terminate)"。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user