Repository navigation
fix: make Insight snapshot artifacts interoperable - #268
Conversation
0c2ca02 to
a6c24f9
Compare
codeasier
left a comment
There was a problem hiding this comment.
故障注入复核(head a6c24f9,配合 msinsight #1305 97cb9726d)
按 owner 决定采用宽松的 parserCache 契约,本评审只关注一件事:数据异常时能否可靠报出清晰错误,不要求 #267 那套严格规则。
测试方法(实测)
- 夹具:25,000 事件,
--events-per-slice 10000,3 片,故障注入在 slice_00001。 - 4 种产物:#268 导出(有 seal)、#1305 首次解析(有 seal)、main 导出(无 seal)、Insight master 输出(无 seal)。
- 共 61 种故障 × 4 种产物 = 244 个用例,每个用例跑
import复用、metadata、overview、query memory_peak。 - 本 PR 相关测试:130 passed。
结论
- 符合预期:
- 删 trace/block/dictionary 表、删列或改列名、删 trace 行、改 block 值、NULL、删 dictionary 条目、截断、文件头损坏、删成员或 0 字节成员、无 PK/重复 id、manifest 各类错误(缺失、JSON 损坏、缺 cacheHash、schemaVersion、sliceCount、区间缺口、not ready、类型错误、
..路径、重复 key、坏 UTF-8)、源文件变化:均报清晰错误。 - GUI 流程(追加
memory_allocation_cache_v1_0、parse.log、活跃的 WAL 读者):都能正常复用。
- 删 trace/block/dictionary 表、删列或改列名、删 trace 行、改 block 值、NULL、删 dictionary 条目、截断、文件头损坏、删成员或 0 字节成员、无 PK/重复 id、manifest 各类错误(缺失、JSON 损坏、缺 cacheHash、schemaVersion、sliceCount、区间缺口、not ready、类型错误、
- 需要处理的问题(详见行内评论):
- 索引页物理损坏仍被复用(实测)→ 在
member_digest里加PRAGMA quick_check。 - 带 seal 的产物被删行或改值后,
import会拒绝,但query/overview直接查目录照常返回数据,metadata也看不出 seal 已失配(实测)。 ADD COLUMN后import显示复用成功,但随后metadata/overview/query全部报错(实测)。ptSnap不是对象时抛AttributeError;manifest 嵌套过深时抛RecursionError(均实测出现 traceback)。- 提示信息有误导:
- 有活跃的 rollback journal(写者正持有锁)时报 "Unrecognized files or aliases";
- main 导出报 "Unsupported or inconsistent pt-snap compatibility identity";
- 有几处直接透出原始异常文本,例如
'metadata'、string indices must be integers, not 'str'、no such table: pt_snap_metadata、[Errno 2] No such file or directory ...manifest.json。
- 未知文件的处理前后不一致:自有路径会拒绝,外部 Insight 路径却接受;而且外部无 seal 的旧产物,删行、改值、索引损坏都会被复用(实测)。
- 索引页物理损坏仍被复用(实测)→ 在
建议补充的最小测试
- 破坏一个基础表索引页 →
import复用和validate_cache都应报错。 - 带 seal 的产物修改一行 →
query/overview应报 seal 失配,或至少metadata要明确标示。 ALTER TABLE trace_entry_0 ADD COLUMN→import和query的结论应一致:要么都接受,要么都在复用阶段报错。ptSnap为[]、parserCache为[]、manifest 嵌套 20 万层 → 都应返回IMPORT_FAILED/invalid,不能出 traceback。- 另一进程对成员执行
BEGIN EXCLUSIVE并保持 → 错误信息应写明"成员正被写入"。 - main(v1)导出 → 提示应写明"旧版导出契约,请改用新目录重新导出"。
- 外部产物目录里多一个未知
.db→ 与自有路径行为一致。
除特别标注"推断"的内容外,以上均为实测;复现脚本在本地,有需要可以提供。本评审仅作说明,不构成 approve 或 request-changes。
Signed-off-by: heiheihei <1395202740@qq.com>
codeasier
left a comment
There was a problem hiding this comment.
复核结论(head 188c245):暂不建议进入再审
我在 Linux 上做了复核,环境是 Python 3.13.5、SQLite 3.46.1。全量测试命令与 CI 的 3.13 job 一致:pytest -m "not nightly" --cov。同时联调了配套的 Ascend/msinsight#1305(2a8c79b)。
1. 上一轮检视意见(基于 a6c24f9)
| # | 问题 | 结论 |
|---|---|---|
| 1 | 索引页物理损坏后仍被复用 | 已修复。读事务内会做 quick_check |
| 2 | 带 seal 的产物被篡改后 query/overview 照常返回 | 已修复。剩一个降级绕过,见 3.2 |
| 3 | ADD COLUMN 后 import 成功、后续全部报错 | 已修复。现在允许在末尾追加列 |
| 4 | ptSnap=[]、嵌套过深的 JSON 产生 traceback |
已修复。嵌套过深时,metadata/query 仍会透出 Python 原文 maximum recursion depth exceeded… |
| 5 | 提示信息误导、透出原始异常文本 | 部分修复。外部产物有 journal 时仍提示 aliased sidecar or rollback journal;query/overview 仍笼统提示 live SQLite sidecar;删掉 parserCache 后 import 报裸 'parserCache' |
| 6 | 外部路径与自有路径不一致;无 seal 的旧产物被篡改后仍可复用 | 部分修复,作者说明为有意为之。无 seal 产物在 query/overview 路径不做 quick_check,索引损坏时报 database disk image is malformed。这一局限目前只写在 PR 描述里,建议写进仓库文档 |
故障注入覆盖 4 种产物(#268 导出、#1305 产物、main v1 导出、Insight master),每种 45 种故障,共 180 个用例;每个用例跑 import、metadata、overview 和 3 类 query,共 6 个入口。结果没有任何 traceback,该拒绝的都拒绝了。
2. 阻塞:全量测试 14 个失败(main f940ff7 为 0)
fork PR 没跑 CI,PR 里说的“相关测试通过”只覆盖了定向子集(93 个)。全量结果:14 failed / 2951 passed / 14 skipped。
- 6 个,在
tests/core/test_msinsight_export_validation.py(boundary/empty shards、rowid alias、non-rowid PK 等)。msinsight_export.py:147的_compact_compatible_block_ids假设每个分片都有block_<dev>表,没有时抛出未包装的sqlite3.OperationalError: no such table: block_0。这是代码问题,需要先判断表是否存在。 - 1 个:
tests/test_dataset_contract.py::test_invalid_sqlite_artifacts_are_locatable[...ADD COLUMN...]。第 3 点放宽了契约,但旧测试没更新。 - 6 个:
tests/test_dataset_focus.py::test_live_sidecar_rejected_before_any_sqlite_open[*-True-*]。报错文案改成了aliased SQLite sidecar,测试仍期望旧文案。 - 1 个:
tests/test_interop_acceptance.py::test_compatible_owned_cache_reuse_and_external_force_preserve_actual_bytes(L166)。行为已改为按外部产物复用,但测试和契约说明没同步。
3. 新发现的问题
- (阻塞,与 #1305 联动)并发写表时校验失败。 msinsight 侧实测发现:Insight 首次导入普通 pickle 时 4/4 失败,报
Snapshot member changed during validation,重试也一直失败;同一文件在 master 上 3/3 成功。原因是 server 已经往标记为 ready 的 slice 写memory_allocation_cache_v1_<dev>,而校验以immutable=1打开同一个库,看到文件变化就中止。pt-snap 复用的是同一套校验逻辑,如果校验时正好赶上 Insight 写派生表,也可能撞上这个错误。建议校验不要用immutable=1,改为等待 SQLite 锁;或者调整顺序,先 seal 再发布 slice。 - (中)删掉 parserCache 就能绕过 seal。 自有产物的
ptSnap.memberHashKind=parser-v1,但 resolver 只检查 parserCache 是否存在。把它删掉再改基础行,query/overview 会照常返回被改过的数据。建议在memberHashKind=parser-v1时强制要求 parserCache 存在,并给出可读的报错。 - (低)
quick_check不核对索引和表内容是否一致。 用 writable_schema 换掉idx_block_0_size后,quick_check 和 seal 都能通过,但走这个索引的结果和全表扫描不一致(97 vs 98 行)。需要刻意篡改才会触发,记为残余风险。 - (低)只读打开会在外部目录创建空
-wal。 外部 WAL 库只有-shm时,mode=ro打开会新建一个 0 字节的-wal。 - (低)文档。
docs/en/sharded-snapshotdb.md:510和docs/zh/sharded-snapshotdb.md:407仍写exportContractVersion=1。另外,放宽后的列契约同时被native_dataset_contract.py:378使用,和 PR 描述里“原生不变”的说法不完全一致。 - (信息) 本 PR 实质上解决了 #266,建议在描述中关联。每次 query/overview 都会做全量 seal 和 quick_check,百万级事件规模下的性能还没验证。
4. 互通(与 #1305 联调)
- 单设备和多设备(2 卡、19 片)场景下,#268 导出与 #1305 解析出的
parserCache.members和 cacheHash 完全一致,salted hash 也一致。 - 双向缓存都能直接命中、不重解析:Insight 写完派生表后,pt-snap 能直接复用;pt-snap 也能读取 Insight 产物并
reused=true。查询结果与memory_peak一致。 - 旧版 Insight(master)也能正常读取新的 pt-snap 产物,所以两个 PR 不必同时合入。
建议
- 修复或更新上述 14 个用例,重点是
_compact_compatible_block_ids的表存在性判断。 - 补上 parserCache 降级校验。
- 和 #1305 一起处理并发写表的校验问题。
- 修正文档中的版本号和局限说明,并关联 #266。
完成后请 owner 批准 fork workflow 跑一次 CI,再进入再审。
本评审仅为 COMMENT,不代表 approve。
|
针对 #268 (review) 的复核意见,当前 head 为 5a49f9a(配套 Insight 200ce403a)。 已处理:
本轮补充 Windows 真实文件双向验证:
完整命令、原始 JSON、日志、对比结果和截图已保存在本机 interop-validation-20261020,两个 producer 原件通过重命名保留以供审核;未将本地截图伪装成远端已上传附件。本轮兼容校验约 84 秒,不宣称常量时间或秒级复用。内置浏览器的 iframe 点击/焦点操作报目标失效,因此没有宣称全部切窗/缩放交互已验收。 补跑结果:Insight 56 项(55 通过、1 因符号链接权限跳过);CLI 四个相关测试文件共 218 项,204 通过、14 项在布置 symlink 时因 Windows WinError 1314 失败,未进入被测逻辑。不是原复核中的 14 个逻辑/文案失败,也不宣称全量 CI 已通过。完整日志保留。两个 source branch 已 push 核对,均为 up-to-date,本轮未产生额外产品代码或空提交。 |
codeasier
left a comment
There was a problem hiding this comment.
复核当前 head 5a49f9a:建议先修复下面两项 P2,再合入。
上一轮反馈的 14 项回归失败在当前 head 已不复现;仅删除 parserCache 绕过 ptSnap seal 的问题、native-v2 精确列合同以及相关诊断/文档问题也已核对修复。两项新增问题都在外部缓存复用入口,具体复现和建议见行内评论。
本轮验证:
- Linux / Python 3.12.14 全量 pytest:2993 passed、16 skipped、0 failed,耗时 513.56 秒。
- 387 项相关回归另外全部通过,未排除 Linux 符号链接用例。
- 21 个改动 Python 文件的 Ruff、Black 以及 git diff --check 通过。
- basedpyright:0 errors / 1838 informational warnings;未做 warnings 基线差分。
- 16 个跳过项包含浏览器、条件性生命周期及未配置 wheel 的 installed-scale 验收;本轮未做真实 Insight GUI、百万事件 installed-wheel 或全平台验收。
远端该 head 的 CI 与 Cross-platform 合同运行目前仍为 action_required,不能视为 CI 通过。本次只提交 COMMENT,不代表 approve。
| # never invent provenance metadata or replace it under force. | ||
| checked = validate_cache(target, cache_hash, options.device) | ||
| manifest = parse_manifest(checked) | ||
| if "parserCache" not in checked: |
There was a problem hiding this comment.
[P2] 不要因为存在 parserCache 就跳过基础结构/语义校验
这条分支把摘要一致当作完整产物有效:validate_cache 会检查摘要、范围、基础列和字典引用,但不执行 P0 对负字节指标、事件动作、块生命周期、跨片身份等的全部检查。可复现:用测试构造的合法外部数据集,将 trace_entry_0 的一行 allocated 设为 -1;无 parserCache 时 import --no-focus 拒绝并报 event_values;对相同基础行生成正确 seal 后,导入却返回 reused=True,而 DatasetResolver.inspect 同一 sealed 产物仍报 event_values。因此来自生产者的摘要自洽但结构非法的产物会被宣布导入成功、随后无法查询。这是入口校验一致性问题,不是声称摘要能认证生产者。请保留共享 P0 校验,或把等价语义检查整合进摘要扫描,并补上 sealed/unsealed 的同一非法产物对照测试。
There was a problem hiding this comment.
采纳,已在 dba7e09 修复并推送。
外部产物不再因存在 parserCache 而跳过共享 P0 校验;同时修复工具自有 parser-v1 产物的同类遗漏。摘要自洽只说明内容一致,不替代结构和语义有效性。外部导入直接调用共享 validate_dataset,避免再通过 resolver 重复执行摘要扫描。
补充 48 项语义回归组合,覆盖外部/自有产物、有/无 parserCache、启用/禁用 focus,以及负字节指标、非法边界动作、非法块大小、生命周期、跨片身份冲突和末片非法数据;这些用例全部通过。每项还检查 force/非 force 拒绝后源文件、解析目录和已有 focus 不变。工具自有产物的 --no-focus 缺陷已通过先失败再修复的用例复现。
扩大验证共 424 项:413 通过;8 项在测试准备阶段因 Windows 符号链接权限失败,3 项因既有 os.fchmod 在 Windows 不可用失败,未宣称全量通过。Black、Ruff 通过,类型检查 0 errors。
| # A compatible producer is not pt-snap-owned. Reuse read-only; | ||
| # never invent provenance metadata or replace it under force. | ||
| checked = validate_cache(target, cache_hash, options.device) | ||
| manifest = parse_manifest(checked) |
There was a problem hiding this comment.
[P2] 外部缓存命中时仍需检查显式 events_per_slice
新复用路径没有比较用户指定的容量。实测一个合法外部缓存含 5 个真实事件、eventsPerSlice=2、共 3 片,再显式请求 events_per_slice=3,仍返回 reused=True、slice_count=3,实际 manifest 容量保持 2,配置被静默忽略。自有缓存路径会通过 compatible_identity 拒绝容量不匹配,文档也说明该参数设置分片容量、改变选项需新输出目录。CLI/ImportOptions 中该选项默认 None,可以保留省略参数时复用现有容量的行为,只在 options.events_per_slice is not None 时与 manifest.events_per_slice 比对;显式不匹配时保留原目录并提示选择新输出目录。请补充显式不匹配与省略参数分别验证的回归用例。
There was a problem hiding this comment.
采纳,已在 dba7e09 修复并推送。
外部缓存复用时,仅在 options.events_per_slice 非 None 时比较 manifest.events_per_slice;显式不匹配即拒绝复用并提示选择新的输出目录,省略参数时保留既有容量,匹配时正常复用。包括 --force 在内都不会改写或重新解析原外部目录。
容量回归覆盖有/无 parserCache、force/非 force,以及省略参数、匹配容量 2、不匹配容量 3(5 个真实事件、现有 3 片),共 12 项均通过。另有实际 CLI 的省略/匹配成功后查询验证,以及不匹配时 JSON 错误、解析目录/源文件/已有 focus 保留验证,均通过。
📝 Description
Normalize the msinsight-compatible exporter to Insight block/boundary IDs, share source/base-row cache validation with Insight, and support read-only consumer WAL/SHM and derived tables. Avoid repeated full resolver scans without skipping logical validation. Native-v2 numbering is unchanged.
🔗 Related Issue
None; no linked issue.
🧪 Testing
✅ Checklist
Snapshot Runtime Provenance
Snapshot provenance decision: no-update
Snapshot provenance no-update reason: No files under src/pt_snap_cli/snapshot/ change; ID normalization is confined to the core compatibility exporter, leaving native replay/storage and existing provenance untouched.
📸 Screenshots (if applicable)
Local GUI evidence is recorded below. Screenshots remain local and are not claimed as uploaded remote attachments.
📋 Additional Notes
完整验证记录
下文为逐阶段记录,前半部分的失败和限制描述修复前状态,以“修复后验证”和本次复验结果为最终结论。原始证据文件名用于追溯;本机文件路径不是可下载的远端附件。
Insight / pt-snap-cli 实际互用验证
验证时间:2026-10-15。输入:
C:\data\pickle\memory0.pickle(175710540 字节)。结论
关闭且稳定的解析产物可以双向复用,C++ 添加派生表不会导致脚本缓存失效。但不能认定当前两套解析结果完全等价,也不能认定支持正在使用中的 SQLite 产物共享。
环境与调用
http://localhost:5174/实际导入。C:\github\pt-snap-cli当前工作区,安装到独立验证虚拟环境;版本0.4.1.post1.dev0,包含本地互用修改,不是未经修改的发布版。CLI 命令示例(
pt-snap.exe位于验证虚拟环境的 Scripts 下):已验证结果
reused:falseSnapshot cache validatedmemory_allocation_cache_v1_0,原 CLI 表保留reused:true、rebuilt:false、metadata:nullCLI 静态副本保留了 Insight 添加的派生表。只对验证副本执行 SQLite checkpoint,并关闭连接以形成可搬运产物;没有删除原目录的 WAL/SHM。
发现的问题与限制
1. 正在使用的数据库尚不能直接共享
第一次 CLI 复用完整 Insight 产物时,基础校验之后被 DatasetResolver 拒绝:
Dataset member has a live SQLite sidecar。切换项目时 SQLite checkpoint 又使并行校验返回Snapshot member changed during validation。这些检查没有错误使用半成品或变更中的数据,但意味着当前不能宣称支持 GUI 与 CLI 同时直接共享一份正在使用的产物。即使 WAL 长度为零,只要 WAL/SHM 存在,CLI 的后续 dataset 校验仍会拒绝。
2. 源 hash 一致,基础数据并非完全一致
两边 cacheHash 均为:
e7f5c1b59aef07a6602f72fc1db9e5b4a3a19c7e419a21aa8147e9c1519cf64f但两个分窗的基础数据 seal 均不同。已定位的具体差异:
Insight 当前解析器具有
compact_unresolved_block_ids编号压缩逻辑。CLI 兼容导出没有得到相同编号结果。相同源 hash 在前端可能复用不同解析器产生的块图缓存,因此正式替换脚本前仍需统一基础解析语义与缓存身份。此次没有为通过验证修改盐值。详见 base-data-differences.json。
3. 复用不等于秒开
CLI 产物导入 Insight 的缓存验证约 41 秒(15:32:54~15:33:35)。本数据基础表包含大量调用栈文本,逐行 seal 校验和 CLI 后续结构验证耗时明显;不能将这些耗时描述成重新解析,也不能把它忽略。
4. 验证边界
已实际确认 CLI 产物第一个窗口显示。后续 iframe 控件自动化报目标不可用,未完成第二片切换交互验证。跨窗块 485072 的两片信息已通过直接查询数据库核对。
本轮没有修改业务代码、提交或推送代码;保留了所有验证产物以便进一步定位。
文件清单
cli-produced/:CLI 输入副本与其兼容产物,已被 Insight 使用并添加派生表。insight-closed/:Insight 解析产物静态副本,CLI 已成功复用。before-gui.json/after-gui.json:基础 seal、表清单、行数及 ID 范围。base-data-differences.json:代表性记录差异。insight-to-cli.json:在线共享被 WAL/SHM 检查拒绝的记录。insight-to-cli-closed.json:并行 checkpoint 被变更检查拒绝的记录。insight-to-cli-portable.json:静态产物成功复用记录。cli-to-insight.png:GUI 结果截图。修复后验证(2026-10-15)
修改
实测
cli-fixed/memory0.pickle.msinsight,两片基础行摘要与原 Insight 产物完全一致。fixed-artifact-comparison.json记录负块数量、边界 ID 和跨窗块 485072;两边均一致。Snapshot cache validated,未重新回放。insight-to-cli-fixed.json:CLI 复用原 Insight 产物,reused=true、rebuilt=false。cli-after-insight-fixed.json:CLI 再次复用被 Insight 添加派生表的工具产物,reused=true、rebuilt=false。cli-fixed-to-insight.png:修复后 GUI 验收截图。验证限制
提交前复验与范围
风险、兼容性和回滚
本轮检视意见处理
PRAGMA quick_check,拒绝索引页等物理损坏;检查过程不修改源 DB。ptSnap、identity 和相关扩展字段的类型。parserCache的兼容产物核验 seal,复用现有 generation 缓存;SQL 中断与逐行扫描遵守请求 deadline。设备筛选产物按自身 requestedDevice 校验,仍支持查询。--force也保留;本轮不改源 hash 盐值、摘要字节、导出版本或编号。本轮验证
git diff --check通过。Black 使用本机 Python 3.12.14 检查通过,不使用有已知安全限制的 3.12.5 执行格式校验。memory0.pickle验证:Insight 原产物和 CLI 修复产物均 reused=true、slice_count=2;前者 metadata=null,后者保留工具 metadata。两次均使用 --no-focus 等价调用,不触发重新回放。