Skip to content

[FEATURE] 定义分片 SnapshotDB 产物协议与 msinsight 兼容契约 #198

Closed

Description

@codeasier

父 roadmap:#197
实施阶段:P0
依赖:无前置子任务

范围:固定 manifest、SQLite 布局、事件与 block 身份语义,提供生产端与读取端共用的校验合同。

功能描述

为分片 SnapshotDB 定义可版本化、可测试的产物协议,同时明确 pt-snap 原生增强格式与当前 msinsight 兼容格式的边界。

使用场景

同一份分片产物需要在 pt-snap 与 msinsight 间交换。仅按事件数拆 SQLite 文件,无法保证目录发现、堆栈读取、缓存复用和生命周期语义一致。

期望的实现方式

  • 固定兼容布局:<原始 snapshot 路径>.msinsight/manifest.json、device_<id>/slice_<index:05d>.db。
  • 记录并校验 manifest schemaVersion=1、status、sourceFile、cacheHash、eventsPerSlice,以及每设备 eventCount/sliceCount/readySlices/slices;切片记录包括 index/startEventId/endEventId/file/ready。
  • 当前 msinsight 要求每设备区间从 0 连续覆盖到 eventCount-1。定义非零起点/非连续原始 ID 的策略:明确拒绝兼容输出,或显式重新编号并保留可逆原始 ID 映射,不能静默修改身份。
  • 以真实事件位置决定分片容量。负 ID 左边界事件单独标识;事件范围、峰值和真实计数不得被边界事件污染。
  • 固定基础 SQLite 表、列顺序、类型与 dictionary 枚举映射。msinsight 通过实际 table 发现事件表,部分 SELECT * 按列位置解析,兼容 VIEW 不能替代此合同。
  • 定义已解析 block 的跨片稳定身份、未解析/预存 block 的身份及生命周期哨兵值,禁止仅按地址去重。
  • pt-snap 增强 metadata、去重 callstack、有序 frame 数据使用可选扩展表或 sidecar;基础协议版本、pt-snap 导入版本、frame 扩展版本分别管理。
  • 定义整份数据集、设备、单片、事件范围的查询 scope 与能力声明;外部产物不要求 pt_snap_metadata 或辅助引用表。
  • 对缺片、重叠区间、非法相对路径、device/表不一致、未知版本、building 状态给出可定位的校验错误;首版完整分析仅接受最终化的 complete 数据集。

验收标准

  • 中英文协议文档包含 manifest 示例、SQLite 列顺序/枚举、事件与生命周期语义。
  • 有共用解析/校验模型及合成有效、无效产物的合同测试。
  • 当前 msinsight 兼容布局通过其真实 manifest 校验规则的对照测试。
  • 非零/非连续 ID、无事件设备、静态 block、负 ID 边界事件的行为有明确决定及测试。
  • 未知增强扩展不影响基础读取;缺少 frames 不得被描述为完整结构化 frame 能力。

参考资源

Activity

  1. codeasier commented on Oct 4, 2026

    @codeasier
    OwnerAuthor

    Issue review

    Reality: 需求成立,属于新增产物协议缺口,并非现有 split 违约:当前只输出 pickle/JSON,再单独导入 DB;原生 v2 使用 callstackId。内存核验表明默认峰值及 overview 包含负 ID,确需明确边界语义。

    Reasonableness: 先冻结共享校验合同合理,但不能以最大 ID 推算真实事件数、按地址合并 block 或静默改号。兼容首版可拒绝非零/稀疏 ID;扩展需命名隔离或 sidecar,v1 直接附加原生 callstack 表会触发布局冲突;文本栈不等于结构化 frames。

    Boundary: P0 限双语协议、共享模型与合成正反合同测试;明确空设备、生命周期哨兵、缓存身份、路径及状态一致性。生产与跨片查询执行留后续;complete 门槛仅约束新数据集完整分析,保留现有单库兼容。

    Evidence:

    Limitations: 已读完整原文及全部 0 条评论,本地 HEAD 等于所引基线。仅做静态及无文件写入的内存检查,未运行 pytest 或产物互通测试。msinsight 指定提交本地缺失、远端 C++ 限流,其真实 manifest/列位置规则尚未完整核实,不能宣称兼容通过。

  2. codeasier commented on Oct 8, 2026

    @codeasier
    OwnerAuthor

    代码已由 #216 合入 origin/main(9 commits 链,tip 7c33464)。按维护决定先关闭本 issue;PR #216 中声明 deferred 的 GUI / C++ server / 安装 wheel 人工验收,以及 #217 系列默认规模不可用问题,另行跟踪。

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