iomgaa
72b6b54719
Both open issues ask the same question from opposite sides: how much power the library holds over a downstream database. #13 wants the structural writes back, #12 wants the data retention back. The two designs share one boundary -- the library does SELECT and INSERT plus an optional CREATE, and everything that alters structure or deletes rows belongs to the downstream, with the library obliged to print the exact SQL they need to run. Two findings shape #13 beyond what the issue argues. The precedents it cites (Hangfire's lock queue, Prefect's multi-instance race, Alembic's audit trail) all live on a shared production Postgres, while the SQLite side is a local file with no DBA and no migration tool, so the defaults split by backend rather than uniformly. And turning ALTER off only works together with trimming the INSERT to the columns that exist: without it a stale table drops every row instead of two columns, which breaks the telemetry rule harder than the automatic ALTER ever did. For #12 only the body cap touches library code; retention and access control land in the README, because the sdist carries src and the README alone -- a template that lives in the wiki is one a downstream pip install cannot reach.
23 lines
3.1 KiB
Markdown
23 lines
3.1 KiB
Markdown
---
|
|
type: design
|
|
node_id: design:issue12-telemetry-retention
|
|
title: "issue #12: 遥测表的正文体量、保留期与访问控制"
|
|
date: 2026-08-19
|
|
---
|
|
|
|
# issue #12: 遥测表的正文体量、保留期与访问控制
|
|
|
|
|
|
正文: `2026-08-19-issue12-telemetry-retention-design.md`。状态: **待人类审批**。同批交付 [[design:issue13-schema-mode]]。
|
|
|
|
- **选定方案**: 三个子问题分层落点——(a) 正文体量: 新增 `PGW_TELEMETRY_TEXT_CAP`,**缺省 None 即不截断**,截断只发生在 `TelemetryEmitter._record`; (b) 保留期: README 分区 + `pg_partman` retention 模板 + `tools/telemetry_retention.py` 独立脚本(默认 dry-run),库本体不持有 DELETE/DROP 权限; (c) 访问控制: 纯文档,三角色划分 + `REVOKE UPDATE, DELETE` + 不可变性说明。
|
|
- **只有 (a) 改库本体代码**,且它是唯一**预防性**手段: 没写进去的数据不需要删。
|
|
- **缺省不截断的理由**(人类决策): 截断后遥测不再是审计证据、也无法复现重放,而这是既有下游正在依赖的行为,默认改动即破坏。代价是 issue 那句"无限期保留全部租户全文不应是默认状态"只解决一半——默认仍是全文,但下游第一次有了不写全文的手段。
|
|
- **按每条文本切而不是切整串 JSON**: 后者产出非法 JSON,让此后一切按 JSON 解析该列的分析全废(SQLite 的 `messages` 是 TEXT 列,不做任何 JSON 校验,坏数据静默存进去)。
|
|
- **不复用 `_http_errors.summarize_body`**: 它折叠空白 + 保头保尾,是为错误 JSON 设计的——折叠空白会破坏正文里的代码块与缩进,保头保尾服务的是诊断而非"不想存全文"。视觉标记口径一致,实现各自独立。
|
|
- **红线**: `digest_messages` 一个字节都不能碰(缓存 key 与遥测共用,`middleware/cache.py:31`),动它 = 全量缓存 miss + key 口径分叉。已设机械化验收: 同一组 messages 在 cap 开关两态下 `build_cache_key` 输出逐字节相同。
|
|
- **权限张力**: 既要 `REVOKE DELETE` 又要清理,就只能走 `DROP PARTITION`(owner 操作)而非 `DELETE`(应用角色)。这是分区方案不可替代的理由,不是性能偏好。
|
|
- **文档必须进 README 而非 wiki**: sdist 只打包 `src/` 与 README(无 MANIFEST.in),wiki 里的模板下游 `pip install` 后读不到——56f3805 的教训。README 的模板 SQL 另设真实 PG 集成测试逐条执行,因为下游照抄错 SQL 就中招。
|
|
- **被否决备选**: 缺省即截断(所有现有下游遥测正文被静默削短);库内建 TTL/清理(库需 DELETE 权限,与 (c) 的 REVOKE 建议直接冲突,且"纯 asyncio 中立、无全局状态"铁律排斥库内定时任务);给 `TelemetryRecorder` 加 `purge_before(ts)`(冻结签名的端口扩展 + 同样的权限冲突);只写文档不改代码(下游唯一手段是不用遥测)。
|
|
- **共同边界(建议入 ARCHITECTURE D15)**: 库对下游库只做 SELECT/INSERT(加可选建表),一切改结构与删数据的操作交给下游,库的义务是把需要执行的 SQL 明明白白告诉下游。本设计与 [[design:issue13-schema-mode]] 各实现它的一面。
|