Skip to content

[ROADMAP] 分片 SnapshotDB 与 msinsight 双向互操作 #197

Closed

Description

@codeasier

功能描述

为 pt-snap 增加可选分库导入和整份数据集分析,复用 MemSnapDump 的“持续倒序回放 + 左边界状态 + 跨片 block 回填”,完成两条互操作链路:

  1. pt-snap → msinsight:同一原始 pickle 经 pt-snap 生成兼容分片,当前 msinsight 打开该 pickle 时复用邻接产物并正确可视化。
  2. 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 共享语义、只读分析、事务发布/回滚、资源关闭及来源治理继续成立。

实施顺序与子任务

阶段 子 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 + 邻接缓存”入口。

参考资源

实际 GUI 验证截图(2026-10-11)

固定 msinsight 版本:101f65b877a267ffd5f66ea3834706057ba243e5。

跨片分配详情

Window 2 中查看 block 1669,显示来自 Window 1 的 allocation event 1669。

跨片分配详情

Window 4 曲线

第四窗口的生命周期曲线与 reserved-memory 曲线。

Window 4 曲线

Window 2 概览

第二窗口(events 2000–3999)与五窗口总览。

Window 2 概览

Activity

  1. codeasier commented on Oct 11, 2026

    @codeasier
    OwnerAuthor

    按已确认的固定目标验收范围完成收尾。实际 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,原表内容与未消费的原始导出均已核验。完整边界见已合入文档。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions