Repository navigation
Description
功能描述
为 pt-snap 增加可选分库导入和整份数据集分析,复用 MemSnapDump 的“持续倒序回放 + 左边界状态 + 跨片 block 回填”,完成两条互操作链路:
- pt-snap → msinsight:同一原始 pickle 经 pt-snap 生成兼容分片,当前 msinsight 打开该 pickle 时复用邻接产物并正确可视化。
- MemSnapDump → pt-snap:原版 MemSnapDump 生成的整个 manifest 分片目录可作为一个 focus,支持事件定位及明确支持的全量分析,无需重新解析或迁移外部库。
本 issue 跟踪 roadmap;子 issue 承担具体实现与验收。当前源码分析尚未完成两端端到端互操作验证。
使用场景与现有差距
现有 pt-snap import/focus/query 围绕单 SQLite DB;split 是独立可回放 pickle/JSON 切片,不能替代贯穿分片的模拟器状态。原生 v2 使用 callstackId,目标 msinsight 消费内联 callstack。原版分片中的 block 会引用片外 alloc/free 事件,因此本片 JOIN 不能保证堆栈完整。全量峰值、生命周期、泄漏与 top-N 也不能普遍直接拼接各片结果。
核心设计约束
- 持续回放、真实事件窗口、左边界重建、跨片身份回填;所有最终化与校验完成后一次发布,首版不公开仍可变的 ready 分片。
- 当前 msinsight 兼容输出采用真实基础表、固定列顺序/dictionary、内联 callstack,布局为
<snapshot>.msinsight/manifest.json与device_<id>/slice_<index:05d>.db。 - manifest 使用其 schemaVersion=1;每设备真实区间从 0 连续覆盖到 eventCount-1。非零/不连续原始 ID 必须显式决定兼容策略,禁止静默丢失原始身份。
- GUI 的 cacheHash 为
SHA256(b"mem_snapshot_parser_v2" + 原始pickle字节);pt-snap 内容/选项/版本缓存另行管理。完整复用判据以目标版本实测为准。 - DatasetResolver 在上层解析设备/分片/事件,Context 保持具体 DB 的只读访问;外部原版产物无需 pt_snap_metadata、allocation_ref、frames 扩展或原始 pickle。
- 片外 alloc/free 来源按 manifest 批量读取;引用扩展只是加速。负 ID 边界记录不能污染真实范围、计数和峰值。
- 全量分析逐模板定义聚合、跨片去重、全局排序/分页、占比分母及 scope/completeness;尚不支持的模板或任意 SQL 不得静默只查一片。
- 原始有序 frames、callstack 去重与 pt-snap 增强能力放在可选扩展表/sidecar。原版文本堆栈支持文本归因,不能保证恢复原始 frame 分层树。
- 单库模式、CLI/API 共享语义、只读分析、事务发布/回滚、资源关闭及来源治理继续成立。
实施顺序与子任务
- [FEATURE] 定义分片 SnapshotDB 产物协议与 msinsight 兼容契约 #198 — 定义分片 SnapshotDB 产物协议与 msinsight 兼容契约
- [FEATURE] 持续倒序回放生成分片 DB,并最终化跨片 block 生命周期 #199 — 持续倒序回放生成分片 DB,并最终化跨片 block 生命周期
- [FEATURE] 将 manifest 分片数据集作为整份 focus,只读兼容 MemSnapDump 产物 #200 — 将 manifest 分片数据集作为整份 focus,只读兼容 MemSnapDump 产物
- [FEATURE] 分库 import 的事务发布、数据集缓存与 focus 回滚 #201 — 分库 import 的事务发布、数据集缓存与 focus 回滚
- [FEATURE] 输出当前 msinsight 可直接复用的兼容分片产物 #202 — 输出当前 msinsight 可直接复用的兼容分片产物
- [FEATURE] 数据集按事件查询与跨片 alloc/free、堆栈来源解析 #203 — 数据集按事件查询与跨片 alloc/free、堆栈来源解析
- [FEATURE] 整份分片数据集的峰值、生命周期与堆栈聚合语义 #204 — 整份分片数据集的峰值、生命周期与堆栈聚合语义
- [FEATURE] 建立分库与 msinsight 双向互操作验收、性能基线和文档 #205 — 建立分库与 msinsight 双向互操作验收、性能基线和文档
| 阶段 | 子 issue | 前置依赖 | 交付范围 |
|---|---|---|---|
| P0 | #198 | 无 | 固定 manifest、SQLite 布局、事件与 block 身份语义,提供生产端与读取端共用的校验合同。 |
| P1 | #199 | #198 | 一次加载与持续模拟器状态,多库写入、左边界重建、跨片 block 回填和稳定身份。 |
| P1 | #200 | #198 | 数据集模型、DatasetResolver、focus、overview 与只读 Context 资源管理。 |
| P2 | #201 | #198、#199、#200 | 接入 import 参数和服务,完整暂存后发布,包含数据集缓存身份与失败回滚。 |
| P2 | #202 | #198、#199、#201 | 固定基础表与内联堆栈、目录和 salted hash,让 GUI 导入原始 pickle 时复用 pt-snap 产物。 |
| P2 | #203 | #198、#200 | 事件路由、片外申请/释放引用、活跃内存归因与结构化 frame 能力回退。 |
| P3 | #204 | #198、#200、#203 | 按模板定义跨片聚合、去重、全局排序分页、结果覆盖范围与不支持能力。 |
| P4 | #205 | #198、#199、#201、#202、#200、#203、#204 | 两条端到端链路、差分数据与真实 GUI 复用证据,补中英文说明、来源与性能限制。 |
P0 先固定协议;P1 分别建立写库与读取基础;P2 接入 import 发布、兼容输出和事件级分析;P3 完成逐模板全量聚合;P4 汇总端到端证据。合同测试随各子任务实施,P4 不替代前面的单项验证。
总体验收标准
- 正向:pt-snap 兼容分片被固定版本 msinsight 真实复用,事件、曲线、block 和跨片详情正确。
- 反向:未修改的原版 MemSnapDump 完整产物可整份 focus,并与单库基准完成差分验证。
- 同事件计数器、活跃集合/字节、申请来源、全量峰值、生命周期和泄漏语义一致;跨片全局 top-N 与覆盖元数据可复核。
- 地址复用、跨多片、pending-free、静态/预存、expandable、多设备、合法 OOM/workspace 及 ID 兼容策略有覆盖。
- 缓存/源文件变化、回填/发布/focus 失败有明确错误与可验证回滚。
- frames 扩展保留结构与顺序;原版无扩展产物的能力降级明确。
- 中英文文档、CLI/API 合同、诊断 skills、来源记录与质量检查一致。
边界与性能
分库限制的是每个 DB 的事件量;pickle 仍可能整体加载,长寿命 block 会重复落盘。不将降低加载峰值 RSS 或总磁盘作为未经验证的承诺。首版不做边解析边查询,也不在本仓库修改 msinsight 的独立目录导入入口;兼容目标先锁定上述“原始 pickle + 邻接缓存”入口。
参考资源
- pt-snap-cli 本地基线
09244150ef2a3485aca3d7d23b0f0af0a07f2cb9;msinsight101f65b877a267ffd5f66ea3834706057ba243e5。这些是方案分析基线,实施前应重新核对目标版本。 - msinsight / MemSnapDump:
scripts/MemSnapDump/tools/adaptors/snapshot2db.py、simulate/simulate.py、tools/adaptors/database/snapshot_db.py。 - msinsight server:
MemSnapshotSliceService.cpp、MemSnapshotParser.cpp、MemSnapshotDatabase.cpp。 - pt-snap:
snapshot/simulate/、snapshot/tools/adaptors/、core/import_service.py、context.py、focus/config、query/report。 - 关联 [FEATURE] 兼容 callstack 去重前后的 DB schema:v1 旧库直接只读查询/focus,不迁移 #134(v1/v2 只读兼容)、[FEATURE] 能力清单与数据库概览:减少 Agent 前置探测调用 #142(能力清单与 overview)、[BUG] peak-memory report 丢失归因完整性标志,截断百分比容易被误读 #179(报告归因完整性);扩展其数据集语义,避免重复建同一单库修复。
实际 GUI 验证截图(2026-10-11)
固定 msinsight 版本:101f65b877a267ffd5f66ea3834706057ba243e5。
跨片分配详情
Window 2 中查看 block 1669,显示来自 Window 1 的 allocation event 1669。
Window 4 曲线
第四窗口的生命周期曲线与 reserved-memory 曲线。
Window 2 概览
第二窗口(events 2000–3999)与五窗口总览。



Activity
codeasier commentedon Oct 11, 2026
按已确认的固定目标验收范围完成收尾。实际 GUI/C++ 与原厂生产器反向验收记录已通过 #234 合入;main
ffa71df0ddf0fb5f17a904f4092898a27287d21e的 CI 全部 7 项成功:https://github.com/codeasier/pt-snap-cli/actions/runs/38107096528 。验收文档及去敏结果:https://github.com/codeasier/pt-snap-cli/blob/ffa71df0ddf0fb5f17a904f4092898a27287d21e/docs/zh/interop-acceptance.md 。本 issue 正文保留三张实测截图和原始历史。
本次关闭不扩大承诺:固定 msinsight
101f65b的 Framework/Leaks/C++ 消费端;16组协议/167断言为有界采样,反向覆盖11模板、12时点/6范围。上游 block 详情自动关联 Free Requested 的当前片限制仍明确保留,不是导出事件丢失;GUI新增派生 allocation cache 会改变运行副本字节及成员 attestation,原表内容与未消费的原始导出均已核验。完整边界见已合入文档。