Merged
[MemScope] Unify snapshot cache validation in parser scripts #1305
[MemScope] Unify snapshot cache validation in parser scripts #1305
Merged
heiheiheiAdd on Oct 15
heiheihei
heiheiheiCollaborators
Oct 15

感谢您贡献的Pull Request

在提交之前,请务必阅读 CONTRIBUTING.md。

Thanks for sending a pull request!
BEFORE SUBMITTING, PLEASE READ CONTRIBUTING.md.

PR描述 (What this PR does / why we need it?)

将源文件 hash、完整性和基础数据逻辑摘要校验统一到 Python 解析脚本,C++ 不再重复计算 hash 或以派生表决定是否回放;保留进度与分窗就绪握手。新增可复用缓存契约,允许调用方附加列、表、索引、视图、触发器及无关字典项;Insight 原有编号和 OPFS v1 保持不变。

配套工具仓:https://github.com/codeasier/pt-snap-cli 。本 PR 不关联 Issue。

面向用户的变更 (Does this PR introduce any user-facing change)?

有效的同源解析产物可在 Insight 与工具兼容导出之间复用;消费者派生表不会导致重复回放。hash 盐值不变。Insight 块图 OPFS 版本保持 v1,不要求全量清理既有块图缓存。

功能验证 (How was this patch tested?)

image.png

完整验证记录

下文为逐阶段记录,前半部分的失败和限制描述修复前状态,以“修复后验证”和本次复验结果为最终结论。原始证据文件名用于追溯;本机文件路径不是可下载的远端附件。

Insight / pt-snap-cli 实际互用验证

验证时间:2026-10-15。输入:C:\data\pickle\memory0.pickle(175710540 字节)。

结论

关闭且稳定的解析产物可以双向复用,C++ 添加派生表不会导致脚本缓存失效。但不能认定当前两套解析结果完全等价,也不能认定支持正在使用中的 SQLite 产物共享。

环境与调用

  • Insight:当前工作区构建的后台,9000 端口;通过 http://localhost:5174/ 实际导入。
  • CLI:C:\github\pt-snap-cli 当前工作区,安装到独立验证虚拟环境;版本 0.4.1.post1.dev0,包含本地互用修改,不是未经修改的发布版。
  • 外部 Chrome 连接因授权令牌不可用,实际使用 Codex 内置浏览器访问同一个 5174 服务。
  • 分窗容量均为 500000,设备 0 共 628837 个真实事件、2 个分窗。
  • 原文件未修改;反向验证使用同内容独立副本。原文件此前无相邻解析目录,本轮生成了该目录。

CLI 命令示例(pt-snap.exe 位于验证虚拟环境的 Scripts 下):

pt-snap import C:\data\pickle\memory0.pickle --format msinsight --events-per-slice 500000 --no-focus --json
pt-snap import C:\data\pickle\interop-validation-20261015\cli-produced\memory0.pickle --format msinsight --events-per-slice 500000 --no-focus --json

已验证结果

项目 结果 证据
Insight 首次解析 成功,2 个分窗,后台脚本约 94 秒 原目录 parse.log;后台 15:26:11 至 15:27:45 日志
CLI 首次生成兼容产物 成功,reused:false cli-produced.json
CLI 产物导入 Insight 成功复用,没有重新回放 pickle CLI 产物 parse.log 15:33:35 的 Snapshot cache validated
Insight 派生表 CLI 的两片中均新增 memory_allocation_cache_v1_0,原 CLI 表保留 before-gui.json / after-gui.json
GUI 展示 CLI 产物的第一个分窗生命周期图、缩略轴和事件列表正常出现 cli-to-insight.png
Insight 产物供 CLI 复用 静态副本成功,reused:true、rebuilt:false、metadata:null insight-to-cli-portable.json
CLI 查询 Insight 产物 成功;真实事件范围 0~499999;峰值事件 204412 cli-overview-insight-slice.json / cli-query-insight-slice.json
峰值一致 28554697557 字节,对应 GUI 26.594 GB CLI 查询输出及 GUI 缩略轴

CLI 静态副本保留了 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 均不同。已定位的具体差异:

  • 同一初始块(地址 20624432955392,size 131584,requestedSize 131072),Insight ID 为 -1,CLI ID 为 -44866。
  • Insight 最小块 ID 为 -3810,CLI 为 -53055。
  • 第一片的两个合成事件 ID:Insight 为 -9/-8,CLI 为 -2/-1,对应地址和 size 相同。
  • 跨窗块 485072 在两边两片中一致:申请 485072、释放 582452、地址 21058799960064、size 301989888。
  • 每片事件总数和块总数相同,但这不足以证明全部字段或行为等价。

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 兼容导出版本升至 2:预存块负 ID 压缩到 -1~-3810,跨分窗合成事件统一全局负 ID;原生格式不变。
  • 兼容数据读取允许有效的消费者 WAL/SHM,使用只读事务,禁止忽略 WAL;拒绝回滚日志与旁路符号链接。
  • 复用时删除重复全量 resolver 扫描,基础行 seal 仍完整校验;重复调用栈编码有界缓存,不改变摘要格式。
  • 校验期间 manifest 变化拒绝接受;Windows focus checkpoint 兼容没有 os.fchmod 的环境。
  • Insight 块图 OPFS 缓存版本保持 v1,源文件 hash 盐值不变;CLI 编号对齐 Insight 原有结果。

实测

  • 新 CLI 产物位于 cli-fixed/memory0.pickle.msinsight,两片基础行摘要与原 Insight 产物完全一致。
  • fixed-artifact-comparison.json 记录负块数量、边界 ID 和跨窗块 485072;两边均一致。
  • 页面导入新 CLI 源副本后,parse.log 在 15:58:09 输出 Snapshot cache validated,未重新回放。
  • GUI 第一窗生命周期图、分窗缩略轴和事件列表正常显示;第一窗峰值 26.594 GB / 事件 204412。
  • 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 验收截图。
  • GUI 此次缓存验证约 31 秒,不代表所有缓存均可秒开;完整基础行摘要仍有读取成本。

验证限制

  • 浏览器自动化能观察 iframe 内容,但点击第二窗报目标不可用,未宣称完成第二窗交互验收;第二片数据库已经核对。
  • 工具定向回归中 132 项通过、8 项失败(均为 WinError 1314,无法建立符号链接),另有 6 项同类权限用例未执行。
  • 后续补充 manifest 竞态及编码等价测试;Insight 解析/缓存回归 33 项通过。
  • 最终补充回滚日志拒绝用例后,缓存回归 17 项通过;工具缓存/兼容导出定向回归 66 项通过、6 项权限相关用例未执行。
  • Ruff 与类型检查通过(类型错误为 0,存量 warnings 保留)。本次未提交、推送或额外构建 C++。

提交前复验与范围

  • Insight 解析/缓存回归:34 项通过。
  • 工具 fixture、缓存、兼容导出回归:73 项通过,6 项 Windows 符号链接权限相关用例未执行。
  • 更广定向回归:132 项通过,8 项失败均为 WinError 1314(创建符号链接前置操作失败),不是缓存断言失败。
  • Insight 全部适用 pre-commit hooks 通过;原缓存权限异常通过独立 PRE_COMMIT_HOME 解决,没有跳过 hook。
  • 工具 Ruff 通过,basedpyright 0 errors / 1813 informational warnings。
  • Black 本机检查受 Python 3.12.5 已知内存安全版本限制而拒绝运行,未声称通过;未降低 CI 的格式检查门禁。
  • 两仓 git diff --check 通过。未提交 pickle、数据库、日志、截图或无关 pycache。
  • 本次提交阶段未重新构建 C++ 或执行 C++ UT 全量;先前当前工作区后台已构建并运行,用于下述 GUI 集成验证。
  • 不关联 Issue,不设置里程碑。完整远端 CI 结果以 PR 当前 head 为准。

风险、兼容性和回滚

  • hash 盐值保持 mem_snapshot_parser_v2,source hash 不变;旧工具 owned export 使用旧兼容版本时拒绝原地覆盖,需新输出目录重建。
  • CLI 的 msinsight 兼容导出向 Insight 编号规则对齐;真实事件 ID、CLI 原生 v2 编号不变。
  • WAL/SHM 存在时使用 SQLite 只读事务;基础数据变化、回滚日志、路径别名及校验期间 manifest 变化仍拒绝复用。
  • 基础 seal 需读取基础行,不能把缓存命中等同于秒开;31 秒与41秒是本机单次观察,不是稳定性能承诺。
  • 第二窗数据库内容已核对,但浏览器 iframe 点击受自动化故障阻断,第二窗切换交互未完整验收;未进行全量跨平台/百万事件 installed-wheel 验收。
  • 两个 PR 配套但不强制同时合入:旧 Insight 仍能读取新兼容基础表,新 Insight 对无逻辑 seal 的历史产物保留结构/范围校验,不伪造历史完整性证明。
  • 回滚代码后如复用旧解析目录,应遵循对应导出版本规则;OPFS 版本保持 v1,本次没有引入版本隔离或强制失效。

当前实现说明(以此为准)

OPFS 版本保持 v1,不升级缓存版本。CLI 兼容导出对齐 Insight 原有编号,不改变 Insight 解析结果。缓存契约仅保留在 PR 描述,不单独提交说明文档。

Snapshot 解析缓存契约

职责边界

  • Python 负责计算源文件 hash、校验 manifest/全部分片、决定复用或重新解析、清理旧分片。
  • C++ 每次导入调用 Python,不再维护解析盐值,不再传 --cache_hash。
  • C++ 只构建 allocations 等派生数据,并保留读取 manifest、发送进度/分窗事件的职责。
  • --cache_hash 暂保留为旧调用兼容参数,但脚本忽略其值,不能用它伪造缓存身份。

缓存身份和完整性

util/snapshot_cache.py 定义 SHA256(b"mem_snapshot_parser_v2" + 原始文件字节),
以流式读取计算 hash;缓存命中不反序列化 pickle。盐值没有升级。

manifest 必须完整,所有分片必须 ready,DB 必须存在,基础表字段、主键和真实事件区间必须完整。
新产物在最终回填完成后添加 parserCache,记录每片基础数据的逻辑 SHA-256:

  • trace_entry_<device> 的基础字段,按 ID 排序;
  • block_<device> 的基础字段,按 ID 排序;
  • dictionary 中属于这两张基础表的条目,按四列排序。

校验流式遍历 SQLite 记录,不将全部结果加载到内存。额外列、表、索引、视图、触发器和其它表的 dictionary
条目不属于基础解析产物,调用方可以增加、更新或删除,VACUUM 也不会导致缓存失效。
调用方不能修改基础表及其字典内容,否则逻辑摘要不匹配,需重新解析。
摘要是完整性检查,不是签名,也不能替代 pickle 的信任审核。

旧产物没有 parserCache 时仍检查源 hash、完整 manifest、全部 DB 和基础结构/事件范围;
由于没有历史逻辑摘要,不能追溯检测所有历史基础字段修改。
参数 events_per_slice 不会让已有有效缓存重新分窗;要改变既有分窗请显式移除解析产物。
按设备生成的缓存不能代替全设备缓存。

双仓互用

当前配套工作区:C:\github\pt-snap-cli。
该仓 core/snapshot_cache.py 使用相同逻辑契约。兼容导出使用 --format msinsight,
原生 v2 和默认单库不是 Insight 分窗输入。

新兼容导出的 ptSnap.members 使用 memberHashKind=parser-v1,不再以整个 DB 文件字节作为
缓存有效性依据。旧工具导出没有此标记时保留原有物理校验,不能将其自动升级为已验证的新摘要。
工具可只读复用 Insight 生成的有效兼容目录;缺少工具来源元数据时返回 metadata=null,不改写 DB。
工具普通 import 对无效外部目录仍拒绝覆盖;Insight 管理的解析目录则整体重建。

脚本与后台握手

日志行 Snapshot cache validated: <hash> 表示已验证缓存;
Snapshot cache rebuild: <hash> 在旧 manifest 清除后输出,表示开始重新生成。
C++ 在收到握手前不发布旧 manifest 的分窗,最终还需脚本成功退出和 complete manifest。
前端 fileHash 仍由后台事件传递,其值来自脚本生成的 manifest。

当前仍使用 Insight 自带解析脚本,未切换为外部工具命令。未来替换入口时需要保留
进度日志、握手和分窗就绪通知契约,不能仅替换可执行文件名称。

本轮检视修复与验证(提交 2a8c79b5a)

  • 修复 C++ 测试对间接命名空间引入的依赖,使用完整限定名。
  • 在只读事务内执行 PRAGMA quick_check,拒绝二级索引等物理损坏的缓存。
  • 区分写锁占用与失效缓存;重建前预检全部现存 device DB,即使 manifest 缺失也不删除被检测为正在写入的产物。预检不是跨进程全程目录互斥,不能消除之后新写者进入的全部竞态。
  • 旧工具物理摘要保持验证,补充 dictionary 引用校验;无历史摘要的旧 Insight 产物仍不能追溯证明所有基础字段未被篡改。跨窗 alloc/free ID 允许位于其它分窗,不能按当前窗范围拒绝。
  • 深层 JSON 递归错误转为失效重建;目录准备失败记录错误并返回 False;补充缓存校验开始和逐成员完成日志,不新增 GUI 校验百分比。
  • Python 定向测试共 45 项:44 项通过,1 项因 Windows 符号链接权限跳过;强化后的索引损坏集成测试单独复跑通过。
  • 适用 pre-commit 全部通过。GCC 11.2 对目标 C++ 测试文件的 -fsyntax-only 检查通过;未全量构建或运行 C++ UT,当前 head 的远端 CI 尚未验证。
  • 本轮加固只提交到 Insight;配套工具 PR 未同步这些新增加固改动。
    ——msdevflow
likedislike
Pull Request has been successfully merged by ascend-robot.
(Thank you for heiheihei's contribution.)
heiheiheiheiheiheiCollaborators
Oct 15 Created pull request, commit 7d7abb4d
atomgit-bot
atomgit-bot
Oct 15 Comments:

🤖 AI Code Review

⚠️ 审查未能完成

本次代码审查未能完成,可能是临时性故障。

你可以在评论区输入 /ai summary 重新发起审查。若多次失败,请联系管理员并附上下方追踪 ID。

追踪 ID: task-367838

likedislike
Incorrect?
atomgit-bot
atomgit-bot
Oct 15 Comments:

🤖 AI Code Review

⚠️ 审查未能完成

本次代码审查未能完成,可能是临时性故障。

你可以在评论区输入 /ai review 重新发起审查。若多次失败,请联系管理员并附上下方追踪 ID。

追踪 ID: task-367839

likedislike
Incorrect?
ascend-robotascend-robotCollaborators
Oct 15 Added label: ascend-cla/yes
173 messages are collapsed here。 See more
ascend-robotascend-robotCollaborators
Oct 21 Added label: lgtm
codeasier
codeasierCollaborators
Oct 21 Comments:

/approve

likedislike
ascend-robotascend-robotCollaborators
Oct 21 Added label: approved
ascend-robotascend-robotCollaborators
Oct 21 Merged pull request, merge node SHA: 759e5050a59ed29aa5b45c9d7ba621d88f408b05
ascend-robot
ascend-robotCollaborators
Oct 21 Comments:

Pull Request 已合并或已关闭。

If you want to solve this problem, you can click here to do it in the FAQs.

likedislike