Closed
MemSnapshot 生命周期图分窗 #545
heiheiheiAdd on  Sep 7Closed at  Sep 14
heiheihei
heiheiheiCollaborators
Sep 7 Create

MemSnapshot 生命周期图分窗解析与按需渲染

状态(Status):Draft
作者(Authors):@ayatoychen
创建日期(Created):2026-09-07
更新日期 (Updated): 2026-09-07
相关 Issue/RFC:

1. 概述

1.1 背景

MindStudio Insight 导入 PyTorch 内存快照后,需要通过生命周期图展示内存块从申请到释放的堆叠变化。原有实现将整份快照解析成单个 SQLite 数据库,前端再一次性查询全部 block 并计算绘制路径。

随着快照事件数和同时存活的内存块数量增长,该链路存在以下问题:

  1. 用户必须等待整份快照解析完成后才能查看任何数据,首屏等待时间长。
  2. 单次数据库查询和 WebSocket 响应过大,经过 JupyterLab 等代理时可能超过消息大小限制。
  3. 前端路径构建的时间和内存占用随 block 数、活动块回溯次数快速增长,极端数据可能长时间无法完成。
  4. 单次申请过大的 GPU buffer 可能失败,Canvas 回退路径也会因全量数据而卡顿。

1.2 方案概述

系统按固定事件数将每个 device 的快照拆分为多个分窗,当前产品默认每窗最多包含 500000 个原始 trace event。解析按事件 ID 从右向左倒序生成分窗,使最接近快照时刻的窗口优先可用。

每个分窗拥有独立 SQLite 数据库;全局 manifest.json 描述分窗数量、事件范围、文件位置和就绪状态。第一个分窗完成后,后端立即通知前端加载;其余分窗继续在后台解析,并通过进度事件和分窗就绪事件增量更新页面。

前端只为当前选中的分窗查询 block、事件列表、状态和详情。生命周期路径计算完成后写入 OPFS,缓存身份由源文件 hash、deviceId、eventType 和 sliceIndex 共同组成。再次切换到同一分窗时优先命中缓存,不再请求 blocks 接口。

全局趋势由各分窗的预计算 allocations 概览拼接而成;每段宽度按照该分窗实际事件数占全局事件数的比例确定。生命周期图、内存池状态和详情等数据仍只表示当前分窗。

1.3 目标

  1. 大快照无需等待全量解析完成,首个可用分窗生成后即可进入页面。
  2. 将单次数据库、网络传输、前端路径计算和 GPU buffer 的规模限制在当前分窗内。
  3. 保证跨分窗内存块的身份、申请事件和释放事件语义一致。
  4. 提供全局解析进度、分窗就绪状态和完整的全局内存趋势。
  5. 支持从分窗下拉框或缩略轴切换窗口,未解析完成的窗口不可选择。
  6. 生命周期图只按需计算当前分窗;完成后写入 OPFS,重复访问直接复用。
  7. 数据库、manifest、预计算概览或 OPFS 缓存不完整时能够可靠失效和恢复。
  8. 保持文件 hash 与解析盐值控制的后端解析缓存逻辑,并避免不同 device、eventType 或分窗错误复用前端缓存。
  9. 保持旧 MemScope DB、无 OPFS 环境和 Canvas 回退路径的基本兼容性。

1.4 非目标

  1. 本 RFC 不改变 PyTorch snapshot pickle 的采集格式。
  2. 本 RFC 不保证每个分窗最终生成相同数量的 block;分窗边界由事件数确定,跨窗存活块会出现在多个窗口中。
  3. 本 RFC 不解决 pickle 初始反序列化必须加载原始对象的问题,该方向由 Issue #528 的流式化和内存优化继续跟踪。
  4. 本 RFC 不预计算所有分窗的 OPFS 生命周期路径,只在用户选中分窗后计算。
  5. 本 RFC 不要求兼容模式具备“首片完成即展示”的增量能力;不支持 OPFS 时仍使用现有内存/Canvas 回退路径。
  6. 本 RFC 不改变 Memory/leaks/* 的 MemScope 业务语义。

2. 用例分析

2.1 首次导入大快照

场景:用户首次导入包含多个分窗的 pickle。

预期结果:

  1. 页面立即进入整份快照的解析状态,进度按所有 device 的总事件数计算。
  2. 解析器优先生成最大 sliceIndex 的分窗。
  3. 首个分窗 ready 后,页面选择该分窗并开始加载生命周期图,但全局解析进度继续显示。
  4. 后续分窗 ready 后解除对应下拉项和缩略轴分段的禁用状态。
  5. 全部分窗完成反插、完整性校验和预计算后,整份数据的解析状态才结束。

2.2 在解析过程中切换分窗

场景:当前分窗的 blocks 请求或 OPFS 路径构建尚未完成,用户切换到另一个已就绪分窗。

预期结果:

  1. 旧分窗请求和 Worker 任务通过 generation/request identity 失效。
  2. 旧任务后续返回的数据不得覆盖当前分窗状态。
  3. 当前窗口独立显示 loading,完成后只提交当前 generation 的路径和缩放信息。
  4. 未就绪分窗不可通过下拉框、键盘或缩略轴点击进入。

2.3 重复切换已缓存分窗

场景:用户从分窗 1 切到分窗 2,再切回分窗 1。

预期结果:

  1. 使用 fileHash-deviceId-eventType-sliceIndex 定位 OPFS 缓存。
  2. 缓存为 complete 且结构版本匹配时,直接加载 metadata 和路径 batch。
  3. 命中缓存后不调用 Memory/snapshot/blocks,只请求当前仍需要刷新的折线、事件或详情数据。
  4. 缓存缺失、building、损坏或版本不匹配时,仅重新计算当前选中分窗。

2.4 解析中断后重新导入

场景:解析过程中关闭页面、切换项目或终止后台,产物目录中存在 building manifest、部分 DB 或缺失的概览缓存。

预期结果:

  1. 后端不把部分产物判定为解析完成。
  2. 重新解析前整体清理旧 device 目录、manifest 临时文件和残缺产物。
  3. 不复用解析中断时产生的 OPFS building 缓存。
  4. 页面重新收到全局解析进度和首个分窗就绪事件。

2.5 解析产物部分丢失

场景:manifest 标记 complete,但任意分窗 DB、必要表、数据范围或 allocations 预计算结果缺失。

预期结果:

  1. 后端将整份快照判定为缓存无效,而不是只补单个文件。
  2. 关闭并释放旧数据库句柄。
  3. 删除旧解析产物后整体重新解析。
  4. 解析完成前不向前端报告 snapshotParsingComplete=true。

2.6 导入旧 MemScope 数据

场景:用户导入已有的 leaks_dump/memscope_dump SQLite 数据库。

预期结果:

  1. 继续走 Memory/leaks/* 接口,不进入 MemSnapshot 分窗路由。
  2. 不使用持久化快照 OPFS cache key。
  3. 若旧 blocks 响应未携带有效的时间边界,前端从 block 申请/释放时间推导生命周期窗口。

3. 方案设计

3.1 总体架构

flowchart LR
    Pickle[Snapshot pickle] --> Hash[源文件 SHA-256 + 解析盐值]
    Hash --> Check{解析缓存完整?}
    Check -- 是 --> Manifest[读取 manifest]
    Check -- 否 --> Clean[清理旧产物]
    Clean --> Reverse[按 device 倒序回放]
    Reverse --> SliceDB[分窗 SQLite]
    SliceDB --> Backfill[跨窗块反插与负 ID 收敛]
    Backfill --> Overview[生成 allocations 概览缓存]
    Overview --> Manifest
    Manifest --> Server[C++ 分窗路由]
    Server --> Frontend[分窗选择与全局缩略轴]
    Frontend --> Blocks[按需查询当前分窗 blocks]
    Blocks --> Worker[Worker 路径计算]
    Worker --> OPFS[complete OPFS cache]
    OPFS --> Canvas[WebGL / Canvas 绘制]

3.1.1 关键类关系图

classDiagram
    direction LR

    class MemSnapshotParser {
        -MemSnapshotParserContext parseContext
        +AsyncParseMemSnapshotPickle(path)
        +CheckIfParsingNeed(context) bool
        +SendReadySliceEvents(notifiedSlices)
        +ParseCallBack()
    }

    class MemSnapshotParserContext {
        -string picklePath
        -string outputDbPath
        -string logPath
        -string fileHash
        -ParserState state
        -uint8 progress
        +SetProgress(progress)
        +MarkInitialSuccessSent(complete)
    }

    class MemSnapshotSliceService {
        +LoadManifest(snapshotPath)
        +ResolveSlice(manifest, deviceId, sliceIndex)
        +ResolveSliceDbPath(snapshotPath, slice)
        +BuildDatabaseKey(snapshotPath, deviceId, sliceIndex)
    }

    class MemSnapshotSliceManifest {
        +int schemaVersion
        +string status
        +string cacheHash
        +int64 eventsPerSlice
        +devices
        +IsValid() bool
        +IsComplete() bool
    }

    class MemSnapshotRequestHandler {
        +GetMemSnapshotDatabaseByRequest(request, deviceId, sliceIndex)
        +GetMemSnapshotSliceByRequest(request, deviceId, sliceIndex)
    }

    class DataBaseManager {
        +GetMemSnapshotDatabase(dataKey)
        +ClearMemSnapshotDatabases()
    }

    class SnapshotSliceManifest {
        +dict data
        +mark_ready(device, sliceIndex)
        +mark_complete()
        +save()
    }

    class SimulateDeviceSnapshot {
        +replay_until(sliceStart, progressCallback)
        +register_hooker(hooker)
        +register_allocator_hooker(hooker)
    }

    class DumpEventHooker {
        +pre_undo_event(event, snapshot)
        +post_replay_free_block(block, snapshot)
        +dump_left_boundary(snapshot)
        +flush(device)
    }

    class TruncatedBlockRegistry {
        -nextBlockId
        -pending
        -backfills
        +register(block, dbPath, device) int
        +resolve(block)
        +flush_backfills()
        +compact_unresolved_block_ids()
    }

    class Session {
        +string fileHash
        +string deviceId
        +string eventType
        +int selectedSliceIndex
        +snapshotSlices
        +bool snapshotParsingComplete
    }

    class MemSnapshotSliceOverview {
        +renderSlices()
        +selectReadySlice(index)
        +syncViewport(range)
    }

    class BlockWorker {
        +loadMemoryBlockCache(identity)
        +setMemoryBlockData(data, identity)
        +cancelGeneration(generation)
    }

    class BlockDataOPFS {
        -string storageKey
        +loadCompleteCache(fileHash)
        +markCacheBuilding(fileHash)
        +saveCompleteCache(fileHash, metadata)
        +prunePersistentCaches()
    }

    class WebGLRenderer {
        +setDataFromOPFS(storage, batchCount, lines)
        +setZoom(zoom)
        +renderFrame()
    }

    MemSnapshotParser *-- MemSnapshotParserContext
    MemSnapshotParser ..> MemSnapshotSliceService : 校验和读取 manifest
    MemSnapshotSliceService ..> MemSnapshotSliceManifest : 反序列化
    MemSnapshotRequestHandler ..> MemSnapshotSliceService : 解析分窗
    MemSnapshotRequestHandler ..> DataBaseManager : 获取分窗 DB

    SimulateDeviceSnapshot o-- DumpEventHooker : 回放通知
    DumpEventHooker --> TruncatedBlockRegistry : 注册和解析跨窗块
    SnapshotSliceManifest ..> DumpEventHooker : 分窗完成后标记 ready

    Session --> MemSnapshotSliceOverview : 提供分窗状态
    Session --> BlockWorker : 提供当前上下文
    BlockWorker *-- BlockDataOPFS
    BlockWorker --> WebGLRenderer

3.2 解析产物布局

解析产物放在源文件旁的独立子目录,避免多个 DB 和日志散落在源目录:

memory0.pickle
memory0.pickle.msinsight/
├── manifest.json
├── parse.log
├── device_0/
│   ├── slice_00000.db
│   ├── slice_00001.db
│   └── ...
└── device_1/
    └── ...

manifest.json 的核心结构为:

{
  "schemaVersion": 1,
  "status": "building",
  "sourceFile": "C:/data/memory0.pickle",
  "cacheHash": "<sha256-with-parser-salt>",
  "eventsPerSlice": 500000,
  "devices": {
    "0": {
      "eventCount": 628837,
      "sliceCount": 2,
      "readySlices": [1],
      "slices": [
        {
          "index": 0,
          "startEventId": 0,
          "endEventId": 499999,
          "file": "device_0/slice_00000.db",
          "ready": false
        },
        {
          "index": 1,
          "startEventId": 500000,
          "endEventId": 628836,
          "file": "device_0/slice_00001.db",
          "ready": true
        }
      ]
    }
  }
}

manifest 使用临时文件写入并通过 os.replace 原子替换,避免读取到半写 JSON。status=complete 只能在所有 device 的全部分窗生成、反插和最终处理完成后写入。

3.3 分窗边界与倒序回放

对每个 device,按原始 trace entry ID 划分窗口:

sliceIndex = floor(eventId / eventsPerSlice)
startEventId = sliceIndex * eventsPerSlice
endEventId = min((sliceIndex + 1) * eventsPerSlice, eventCount) - 1

当前 C++ 调用脚本时传入:

--events_per_slice 500000

解析顺序为 sliceCount - 1 到 0。每完成一个分窗,脚本先 flush/close 对应 DB,再将 manifest 中该分窗标记为 ready。这样前端最先看到的是最接近 dump 时刻的数据。

分窗限制的是本次回放处理的原始事件区间,不是 block 行数。一个在窗口开始前申请、窗口结束后仍存活的 block 必须作为边界状态写入当前窗口,因此:

单窗 block 数 = 窗内释放/申请形成的块 + 左边界仍存活的跨窗块

在长生命周期块较多时,单窗 block 数可能高于未分窗数据库中的某个局部区间,这是正确性要求,不应通过丢弃跨窗块来强行限制数量。

3.3.1 首次导入与首窗可用时序图

sequenceDiagram
    autonumber
    actor User as 用户
    participant FE as Leaks 前端
    participant FW as Framework
    participant Parser as MemSnapshotParser
    participant Script as dump2db.py
    participant Manifest as manifest.json
    participant DB as Slice SQLite

    User->>FW: 导入 snapshot.pickle
    FW->>Parser: AsyncParseMemSnapshotPickle(path)
    Parser->>Parser: 计算 cacheHash
    Parser->>Manifest: 校验 manifest、DB 和概览完整性

    alt 解析缓存完整
        Manifest-->>Parser: status=complete,全部 slice 有效
        Parser-->>FW: leaksMemoryCompleted(complete=true)
        FW-->>FE: 恢复全部分窗状态
    else 缓存缺失或不完整
        Parser->>Parser: 关闭旧 DB 句柄并清理旧产物
        Parser->>Script: dump2db.py --events_per_slice 500000
        Script->>Manifest: 创建 status=building

        loop 从最大 sliceIndex 倒序到 0
            Script->>DB: 回放当前事件区间并写入分窗 DB
            Script->>DB: 写入左边界活跃 block
            Script->>Manifest: 原子更新 slice.ready=true
            Parser->>Manifest: 轮询发现新 ready slice
            Parser->>DB: 校验 DB 并生成 allocations 概览

            opt 第一个分窗 ready
                Parser-->>FW: leaksMemoryCompleted(complete=false)
                FW-->>FE: 初始化模块并默认选择该分窗
            end

            Parser-->>FW: memSnapshotSliceReady(deviceId, slice)
            FW-->>FE: 解锁对应分窗
            Script-->>Parser: 每 1% 写入整份数据进度
            Parser-->>FW: memSnapshotProgress(progress)
            FW-->>FE: 更新全局解析进度
        end

        Script->>DB: 统一反插 block ID 和 allocEventId
        Script->>DB: 压缩无法解析的负 block ID
        Script->>Manifest: status=complete
        Parser->>Manifest: 最终完整性复核
        Parser-->>FW: leaksMemoryCompleted(complete=true)
        FW-->>FE: 结束全局进度并刷新必要缓存
    end

3.4 跨分窗 block 身份与反插

倒序回放生成较右侧分窗时,部分活跃 block 的真实申请事件尚未被回放。系统为这些 block 写入左边界占位记录:

  1. allocEventId=-1,表示真实申请事件暂时未知。
  2. 使用进程内 tracking ID 为同一 block 在多个分窗中分配一致的临时负 block ID。
  3. block 对象继续保留在模拟器状态中,进入更左侧分窗后继续参与回放。
  4. 后续遇到真实申请事件时,将所有关联分窗中的 id 和 allocEventId 回填为真实申请事件 ID。
  5. 全部回放完成后,仍无法找到申请事件的历史存量块统一压缩为连续负 ID,并同步更新所有分窗。

该机制必须满足:

  1. 同一真实内存块跨分窗时 ID 稳定。
  2. 已知申请事件的 block,最终 id == allocEventId。
  3. 真正没有申请事件的快照初始存量块才允许保留负 ID。
  4. 反插期间 DB 不得被前端以“最终完成”状态使用。
  5. 前端不在每次反插后重新获取当前分窗;只在整份快照最终完成后执行必要的缓存失效和一次刷新。

3.4.1 跨窗 block 反插时序图

以下示例中,block 在分窗 0 申请、跨越分窗 1,并在分窗 2 释放。解析顺序为 2 → 1 → 0。

sequenceDiagram
    autonumber
    participant Replay as SimulateDeviceSnapshot
    participant Hook2 as Slice 2 Hooker
    participant Hook1 as Slice 1 Hooker
    participant Hook0 as Slice 0 Hooker
    participant Registry as TruncatedBlockRegistry
    participant DB2 as slice_00002.db
    participant DB1 as slice_00001.db
    participant DB0 as slice_00000.db

    Note over Replay,DB2: 倒序生成分窗 2
    Replay->>Hook2: 回放到 slice 2 左边界
    Hook2->>Registry: register(block)
    Registry-->>Hook2: 临时 id = -1
    Hook2->>DB2: INSERT block(id=-1, allocEventId=-1, freeEventId=真实释放事件)

    Note over Replay,DB1: 继续倒序生成分窗 1
    Replay->>Hook1: 回放到 slice 1 左边界
    Hook1->>Registry: register(同一 block)
    Registry-->>Hook1: 复用临时 id = -1
    Hook1->>DB1: INSERT block(id=-1, allocEventId=-1, freeEventId=边界值)

    Note over Replay,DB0: 进入分窗 0 并遇到真实申请事件
    Replay->>Hook0: 反向撤销 block 申请
    Hook0->>Registry: resolve(block, allocEventId=12345)
    Hook0->>DB0: INSERT block(id=12345, allocEventId=12345)

    Note over Registry,DB0: 全部窗口生成完成后统一反插
    Registry->>DB2: UPDATE id=12345, allocEventId=12345 WHERE id=-1
    Registry->>DB1: UPDATE id=12345, allocEventId=12345 WHERE id=-1
    Registry-->>Replay: flush_backfills 完成

3.4.2 跨窗 block 状态图

stateDiagram-v2
    [*] --> WindowBoundaryDetected: 右侧分窗左边界仍活跃
    WindowBoundaryDetected --> PlaceholderPersisted: 分配 tracking ID 和临时负 ID
    PlaceholderPersisted --> PlaceholderPersisted: 继续跨越更左侧分窗\n复用相同临时 ID
    PlaceholderPersisted --> AllocationResolved: 遇到真实申请事件
    PlaceholderPersisted --> PermanentlyUnresolved: 全量回放后仍无申请事件
    AllocationResolved --> Backfilled: 更新所有分窗 id 和 allocEventId
    PermanentlyUnresolved --> NegativeIdCompacted: 压缩为连续负 ID
    Backfilled --> [*]
    NegativeIdCompacted --> [*]

3.5 解析状态与事件协议

后端向前端提供三类状态:

事件 用途
parse/leaksMemoryCompleted 初始化模块、fileHash、device、完整分窗描述和 snapshotParsingComplete
parse/memSnapshotProgress 整份快照解析百分比,按 1% 递增
parse/memSnapshotSliceReady 单个 device/slice 已可查询

进度分母为所有待解析 device 的事件总数,不能在首个分窗结束后归零或变为 100%。

第一次收到 ready 分窗时,后端可提前发送 parse/leaksMemoryCompleted,但必须携带 snapshotParsingComplete=false。最终反插、负 ID 收敛、allocations 概览生成和完整性检查完成后,再发送 snapshotParsingComplete=true 的最终事件。

前端首次挂载还会通过 getParseStatus 主动拉取 module、deviceIds、threadIds、fileHash 和分窗状态,避免页面挂载晚于解析事件时停留在初始状态。

3.5.1 整份快照解析状态图

stateDiagram-v2
    [*] --> Init
    Init --> CheckingCache: 收到导入请求并完成 hash 计算
    CheckingCache --> UpToDate: manifest 和所有产物完整
    CheckingCache --> Processing: 缓存缺失或不完整

    Processing --> FirstSliceReady: 第一个分窗 DB 和概览可用
    FirstSliceReady --> MoreSlicesReady: 后续分窗陆续完成
    MoreSlicesReady --> MoreSlicesReady: sliceReady + 全局进度递增
    FirstSliceReady --> Finalizing: 只有一个分窗
    MoreSlicesReady --> Finalizing: 所有分窗 DB 已生成

    Finalizing --> Complete: 反插、负 ID 收敛、manifest 完整性复核成功
    Processing --> Failed: 脚本、日志或产物校验失败
    FirstSliceReady --> Failed: 后续分窗解析失败
    MoreSlicesReady --> Failed: 后续分窗解析失败
    Finalizing --> Failed: 最终校验失败

    UpToDate --> [*]
    Complete --> [*]
    Failed --> [*]

3.6 后端缓存与完整性判断

后端解析缓存身份使用源文件全量内容 SHA-256 与解析逻辑盐值组合计算。修改解析语义时可调整盐值,使相同源文件生成新的 cacheHash。

只有同时满足以下条件才允许跳过解析:

  1. manifest 存在、JSON 可解析、schema 和字段结构有效。
  2. manifest 状态为 complete,所有 device 的 readySlices 与 slices 一致。
  3. manifest cacheHash 与当前源文件 hash 一致。
  4. 所有声明的分窗 DB 均存在。
  5. 每个 DB 均能打开,必要表、必要数据和完成标记有效。
  6. 每个分窗的 allocations 概览缓存存在且可读取。

任一条件失败时,整份产物失效。重新解析前释放已打开的 MemSnapshot 数据库句柄,并删除旧 device 目录、manifest 和临时文件,避免新旧分窗混合。

后端数据库管理器使用 snapshotPath + deviceId + sliceIndex 形成连接身份。切换项目或重新解析时必须关闭旧连接,防止旧 DB 被删除、替换后仍通过悬挂句柄查询。

3.6.1 解析产物完整性判断流程图

flowchart TD
    Start([导入 snapshot]) --> Hash[计算当前 cacheHash]
    Hash --> ManifestExists{manifest.json 存在?}
    ManifestExists -- 否 --> Reparse
    ManifestExists -- 是 --> JsonValid{JSON、schema 和字段结构有效?}
    JsonValid -- 否 --> Reparse
    JsonValid -- 是 --> Complete{status == complete?}
    Complete -- 否 --> Reparse
    Complete -- 是 --> HashMatch{manifest.cacheHash == 当前 cacheHash?}
    HashMatch -- 否 --> Reparse
    HashMatch -- 是 --> SlicesConsistent{sliceCount、slices、readySlices 一致?}
    SlicesConsistent -- 否 --> Reparse
    SlicesConsistent -- 是 --> AllDbExist{所有分窗 DB 存在?}
    AllDbExist -- 否 --> Reparse
    AllDbExist -- 是 --> DbValid{所有 DB 可打开且必要表完整?}
    DbValid -- 否 --> Reparse
    DbValid -- 是 --> OverviewValid{所有 allocations 概览存在且有效?}
    OverviewValid -- 否 --> Reparse
    OverviewValid -- 是 --> Reuse([复用解析产物并恢复分窗状态])

    Reparse[判定整份缓存失效] --> Close[关闭旧 MemSnapshot DB 句柄]
    Close --> Clean[删除旧 device 目录、manifest 和临时文件]
    Clean --> Parse[从最大 sliceIndex 开始整体重新解析]

3.7 分窗接口路由

以下 MemSnapshot 请求增加 sliceIndex:

  1. Memory/snapshot/blocks
  2. Memory/snapshot/allocations
  3. Memory/snapshot/allocationLines
  4. Memory/snapshot/events
  5. Memory/snapshot/state
  6. Memory/snapshot/detail
  7. Memory/snapshot/leakStats

后端通过 manifest 将 deviceId + sliceIndex 解析为具体 DB。请求未显式提供分窗时,可选择该 device 当前最大的 ready slice,兼容首个可用窗口的默认加载。

blocks 和 allocations 支持分页,避免单条 WebSocket 消息超过代理限制。allocations 被拆成两个职责不同的接口:

接口 数据 使用场景
Memory/snapshot/allocations 抽样后的 allocated 概览及极值 缩略轴和当前窗口概览
Memory/snapshot/allocationLines reserved/process/device 折线 当前窗口主图叠加线

allocations 概览在分窗首次生成时由 C++ 预计算并落盘,避免每次请求重复执行抽样。抽样需要保留波峰、波谷和必要的时间跨度插点。

3.8 前端分窗选择

分窗选择器位于页面顶层,因为除全局缩略轴外,生命周期图、状态图、事件、详情、泄漏统计和折线均属于当前窗口。

选择器规则:

  1. 展示窗口序号、总窗口数和事件 ID 范围。
  2. 未 ready 的窗口禁用。
  3. 首次解析时默认选择最先 ready 的最大 sliceIndex。
  4. 完整产物二次加载时保持确定性的默认策略,不依赖 ready 事件到达顺序。
  5. device 或 eventType 改变时重新建立当前窗口上下文。
  6. 切换窗口不清空用户已经创建的生命周期标记;标记按 fileHash、module、deviceId 和 eventType 隔离,并保留其事件语义。

所有异步结果必须携带或闭包捕获当前上下文。至少校验:

fileHash + deviceId + eventType + sliceIndex + requestGeneration

上下文不一致的返回结果直接丢弃。

3.9 全局缩略轴

缩略轴由 DOM/SVG/Canvas 轻量实现,不再为选中窗口单独嵌套 ECharts,避免分段视觉割裂和双向同步竞态。

每个分窗是一段独立区域:

  1. 宽度按 sliceEventCount / totalEventCount 计算,最后一个事件较少的分窗不再占用相同宽度。
  2. ready 分窗绘制 allocations 概览折线和面积填充;未 ready 分窗使用空数据占位。
  3. 分窗边界下方标记事件 ID,明确每段横轴范围。
  4. 当前只允许一个分窗处于聚焦状态。
  5. 点击 ready 分段切换窗口;拖动和缩放只改变当前分窗内部可视范围。
  6. 暗色模式下使用折线下方填充增强可见性。
  7. 缩略轴拖动采用停顿后提交的防抖策略,不在每个 pointer move 上立即重绘主画布。
  8. 主画布缩放和缩略轴滑块保持双向同步,但程序性更新不得重新触发用户输入回路。

默认 Y 轴上限使用同一 device/eventType 所有已知分窗的全局最大值,避免切窗后相同内存量呈现不同视觉高度。

3.10 生命周期路径与 OPFS 缓存

前端只对当前选中分窗执行以下流程:

选择分窗
  -> 生成 cache identity
  -> 查询 OPFS manifest
  -> hit: 直接读取 metadata/path batches 并绘制
  -> miss: 分页请求 blocks
           -> Worker 构建堆叠路径
           -> 分 batch 写 OPFS
           -> 标记 complete
           -> 绘制

cache identity 为:

fileHash-deviceId-eventType-sliceIndex

只使用源文件 hash 会导致同一快照下不同 device、eventType 或分窗串用路径,因此这些维度必须进入身份。

OPFS manifest 使用 building 和 complete 两阶段状态:

  1. 开始写入前标记 building。
  2. 路径 batch、索引和 metadata 全部写入后标记 complete。
  3. 页面关闭或切换导致任务中断时,building 缓存不得命中。
  4. 下次初始化清理残留 building 缓存并重新计算。
  5. 缓存命中时更新 lastAccessedAt。
  6. 淘汰按源文件维度保留最近访问的 10 份数据;同一源文件下的各 device/eventType/slice 缓存作为一组保留。
  7. 当前正在读取或写入的缓存通过保护计数避免被并发淘汰。
  8. 同一个 storageKey 的操作串行化,防止 load、remove 和 build 同时修改目录。

如果 OPFS 不可用,系统根据现有兼容策略使用主线程/Worker 内存路径和 Canvas 回退。该场景不承诺持久化缓存命中。

3.10.1 分窗切换与 OPFS 缓存时序图

sequenceDiagram
    autonumber
    actor User as 用户
    participant UI as 分窗选择器
    participant Handler as dataHandler
    participant Worker as Block Worker
    participant OPFS as BlockDataOPFS
    participant Server as C++ Server
    participant DB as Slice DB
    participant Renderer as WebGL/Canvas Renderer

    User->>UI: 选择 ready 分窗 N
    UI->>Handler: selectedSliceIndex = N
    Handler->>Handler: generation++,旧请求失效
    Handler->>Worker: loadMemoryBlockCache(cacheIdentity, generation)
    Worker->>OPFS: loadCompleteCache(identity)

    alt complete cache hit
        OPFS-->>Worker: metadata + path batch index
        Worker->>Renderer: setDataFromOPFS()
        Renderer-->>Worker: 首帧已提交
        Worker-->>Handler: renderFinished(generation)
        Handler-->>UI: 关闭当前窗口 loading
        Note over Handler,Server: 不发送 Memory/snapshot/blocks
    else cache miss / building / invalid
        OPFS-->>Worker: miss
        Worker-->>Handler: cacheStatus=miss
        Handler->>Server: Memory/snapshot/blocks(deviceId, eventType, N, page)
        Server->>DB: 路由并分页查询 slice N
        DB-->>Server: blocks page
        Server-->>Handler: blocks page
        Handler->>Handler: 合并或打包当前分窗 blocks
        Handler->>Worker: setMemoryBlockData(data, identity, generation)
        Worker->>OPFS: markCacheBuilding(identity)
        Worker->>Worker: 排序事件并构建堆叠路径

        loop 每个已提交 path batch
            Worker->>OPFS: 写入 path、block index 和 metadata
            Worker->>Renderer: 渐进绘制新 batch
        end

        Worker->>OPFS: saveCompleteCache(identity)
        Worker->>Renderer: 提交最终数据和缩放
        Renderer-->>Worker: 最终帧已提交
        Worker-->>Handler: renderFinished(generation)
        Handler-->>UI: 关闭当前窗口 loading
    end

    par 当前窗口折线
        Handler->>Server: Memory/snapshot/allocationLines(..., N)
        Server-->>Handler: reserved/process/device lines
        Handler->>Worker: setAllocationLines(generation)
    and 当前窗口其它数据
        Handler->>Server: events/state/detail/leakStats(..., N)
        Server-->>Handler: 当前分窗结果
    end

3.10.2 OPFS 缓存状态图

stateDiagram-v2
    [*] --> Missing
    Missing --> Building: 当前分窗首次开始路径计算
    Building --> Complete: 所有 batch、索引和 metadata 写入成功
    Building --> Stale: 页面关闭、切窗取消或写入异常
    Complete --> Complete: 命中并更新 lastAccessedAt
    Complete --> Invalid: manifest 版本不匹配、batch 缺失或解析 hash 失效
    Complete --> Evicted: 不属于最近访问的 10 份源数据
    Stale --> Removed: 下次初始化清理 building 缓存
    Invalid --> Removed: 校验失败后删除
    Evicted --> Removed: 淘汰任务删除
    Removed --> Missing

3.11 Worker 渲染与加载状态

Worker 通过 generation 隔离不同分窗任务。路径构建按 batch 写入并可渐进提交,WebGL 渲染器按 batch 创建 GPU buffer,避免一次申请超大 buffer。

loading 状态必须以“用户已看到有效画面”为结束条件,而不是以 blocks 接口返回或 metadata 生成完成为结束条件:

  1. 缓存命中:首帧真正提交后关闭蒙版。
  2. 缓存未命中:当前 generation 的有效路径首帧提交后可展示渐进结果,完整状态在最终帧后收口。
  3. 旧 generation 的 render-finished 消息不得关闭新窗口的 loading。
  4. 加载蒙版覆盖完整画布容器,包括右侧边界和缩放区域。

3.12 生命周期图正确性约束

  1. 分窗内按申请和释放事件顺序构建堆叠路径。
  2. 同一时间戳下保持确定性的事件排序规则。
  3. 跨窗活跃块在窗口左边界插入起始点,在窗口右边界统一收口。
  4. 右边界释放只用于收口,不逐条遍历所有活动块,避免边界处近似 O(n²) 回溯。
  5. 路径抽稀必须保留几何转折和命中测试需要的关键点。
  6. WebGL 与 Canvas fallback 使用相同的 block、折线、缩放和选择语义。
  7. 旧 MemScope blocks 响应的窗口元数据无效时,从 _startTimestamp/_endTimestamp 推导边界。

4. 测试设计

4.1 解析与 manifest 测试

  1. 事件数小于、等于和大于 eventsPerSlice 时,sliceCount 和事件边界正确。
  2. 多 device 分别生成独立目录和分窗列表。
  3. 解析顺序为最大 sliceIndex 到 0。
  4. 每个 ready 分窗的 DB 可独立打开,必要表和事件范围完整。
  5. manifest 临时写入失败时不发布半写 JSON。
  6. 全部流程完成前 status 保持 building。
  7. 解析进度对整份数据单调递增,并按每 1% 输出。

4.2 跨窗 block 测试

覆盖以下 block 生命周期:

  1. 申请和释放都在同一窗口。
  2. 在前一窗口申请、后一窗口释放。
  3. 跨越三个及以上窗口。
  4. 快照开始前已存在且没有申请事件。
  5. 快照结束时仍未释放。

验证:

  1. 同一 block 在所有窗口中的最终 ID 一致。
  2. 可解析 block 的负 ID 和 allocEventId=-1 均被正确反插。
  3. 无申请事件的 block 使用连续负 ID。
  4. 分窗 DB 合并后的生命周期语义与单库解析结果一致。

4.3 后端完整性和路由测试

  1. manifest 缺失、JSON 截断、status=building 时重新解析。
  2. 任意 slice DB 缺失或打不开时整体重新解析。
  3. allocations 预计算缓存缺失时整体重新解析。
  4. hash 不一致时整体重新解析。
  5. deviceId + sliceIndex 路由到正确数据库。
  6. 切换项目后旧数据库连接被关闭。
  7. sliceIndex=-1 时选择当前最大的 ready slice。

4.4 前端调度测试

  1. 首个 ready 分窗到达后页面自动进入可用状态。
  2. 整体解析未结束时,进度条持续存在。
  3. 未 ready 分窗不可选择。
  4. 快速切窗时旧请求结果不覆盖当前窗口。
  5. 最终完成事件只触发一次必要刷新,不在每次反插时重复请求。
  6. device、eventType、sliceIndex 任一变化都会生成新的生命周期上下文。
  7. 分窗切换不删除已有标记。

4.5 OPFS 测试

  1. 首次选中分窗产生 miss,请求 blocks 并写入 complete 缓存。
  2. 第二次选中相同分窗命中缓存且不请求 blocks。
  3. 同一 fileHash 下切换 device、eventType 或 sliceIndex 不串用缓存。
  4. building、缺失 batch、损坏 manifest 和版本不匹配均重新计算。
  5. 写入中切换分窗能够取消旧任务并清理残留状态。
  6. 最近访问的 10 份源数据保留,更旧缓存被淘汰。
  7. 受保护缓存不会在读取/写入过程中被淘汰。

4.6 渲染一致性测试

建议至少使用以下数据:

数据 用途
snapshot_expandable.pkl 常规多分窗功能、缩略轴和缓存切换
memory0.pickle 与覆盖完整事件范围的单库结果比较 block ID 和路径
大规模训练快照 验证单窗性能、活动块回溯和 GPU buffer 分批
旧 MemScope DB 验证非 Snapshot 生命周期图兼容

对比要求:

  1. 分窗实现与单窗实现的 block 身份、大小、申请/释放事件一致。
  2. 各分窗趋势拼接后的全局极值与完整数据一致。
  3. WebGL、Worker fallback 和 Canvas fallback 的几何结果一致。
  4. 缓存 miss 与 cache hit 的首帧图形、缩放和命中测试一致。

4.7 性能验收

建议记录以下指标:

阶段 指标
Python 解析 首片可用时间、总解析时间、峰值 RSS
C++ 服务 分窗 DB 打开时间、概览预计算时间、峰值句柄数
WebSocket blocks/allocations 单页大小、总请求数、是否触发代理限制
Worker 当前分窗路径构建耗时、峰值内存、活动块回溯次数
OPFS 写入大小、首次写入耗时、命中加载耗时
Renderer 首帧时间、GPU buffer 峰值、切窗交互延迟

验收原则:

  1. 首片可用时间显著早于整份数据完成时间。
  2. 单个 blocks 响应不超过既定分页和代理安全阈值。
  3. OPFS 命中后不执行 blocks 请求和路径重建。
  4. 单窗构建必须能够结束,不允许因边界回溯形成不可收敛的 O(n²) 路径。
  5. 分窗后的峰值前端内存和 GPU buffer 规模应受当前窗口数据约束。

5. 缺点和风险

5.1 分窗事件数不等于 block 数上限

跨窗活跃块会复制为边界状态。如果大量 block 长时间存活,靠近左边界的窗口仍可能包含很多 block。

应对:保留正确性;路径构建使用链表索引、边界统一收口、batch 落盘和渐进渲染。必要时后续引入按活动块规模动态切窗,但不能简单丢弃跨窗块。

5.2 倒序生成导致默认窗口语义变化

首次解析时最先 ready 的是最后一个窗口,完整缓存二次加载时所有窗口同时 ready。如果默认选择策略依赖事件到达顺序,两种场景会不一致。

应对:明确默认选中策略,由前端根据解析状态和 ready 集合确定,不依赖通知时序。

5.3 反插修改已经 ready 的数据库

跨窗块反插会更新先前生成的 DB。如果前端在反插过程中持有旧查询结果或 OPFS 缓存,最终 block ID 可能不一致。

应对:首片可查询但整份数据保持 snapshotParsingComplete=false,此阶段不生成持久化 OPFS cache identity;最终完成时失效临时路径并刷新当前窗口一次。

5.4 产物数量增加

每个 device 产生多个 SQLite 文件,文件数量、manifest 管理和数据库连接生命周期更复杂。

应对:产物集中在 .msinsight 目录;数据库按上下文惰性打开;切换项目及时关闭;完整性检查以 manifest 为唯一入口。

5.5 OPFS 占用持续增长

fileHash 加入 device、eventType 和 sliceIndex 后,一份源数据可能产生多个缓存目录。

应对:淘汰按源文件 hash 聚合,只保留最近访问的 10 份源数据,并清理 building 和损坏缓存。

5.6 HTTP/Jupyter 环境限制

OPFS 依赖安全上下文。普通远程 HTTP 或某些 iframe/代理配置可能无法使用持久化文件系统。

应对:保留能力探测和 fallback;部署侧优先使用 localhost 或 HTTPS。兼容路径只影响缓存和性能,不应影响基本图形正确性。

5.7 全局趋势与当前窗口数据来源不同

缩略轴是多分窗概览拼接,主图折线和 block 是当前窗口数据。如果概览缓存版本或极值聚合不一致,会造成缩略轴与主图比例不一致。

应对:概览与分窗 DB 作为同一解析产物校验;全局最大值按 device/eventType 聚合;最终完成前明确展示未就绪占位。

6. 兼容性

场景 处理方式
新前端 + 新分窗产物 使用 manifest、sliceIndex 和 OPFS 按需缓存
新前端 + 旧单 DB Snapshot 无 manifest 时继续走单库兼容路由
新前端 + MemScope DB 使用 Memory/leaks/*,不进入分窗逻辑
OPFS 不可用 使用内存路径和 Canvas/WebGL fallback
fileHash 为空 使用临时 storageKey,不保存持久化缓存
解析产物缺失 整体清理并重新解析
前端晚于解析事件挂载 通过 getParseStatus 主动恢复状态

附录

B. 关键代码位置

能力 路径
C++ 解析调度与 hash server/src/modules/memsnapshot/parser/MemSnapshotParser.cpp
manifest 解析与 DB 路由 server/src/modules/memsnapshot/service/MemSnapshotSliceService.cpp
Python 分窗与反插 scripts/MemSnapDump/tools/adaptors/snapshot2db.py
前端请求调度 modules/leaks/src/components/dataHandler.ts
分窗缩略轴 modules/leaks/src/components/MemSnapshotSliceOverview.tsx
顶层分窗选择 modules/leaks/src/components/leaks/leaks.tsx
OPFS 缓存 modules/leaks/src/leaksWorker/tools/BlockDataOPFS.ts
路径计算 modules/leaks/src/leaksWorker/tools/dataProcess.ts
Worker 渲染入口 modules/leaks/src/leaksWorker/blockWorker/index.ts
likedislike
heiheiheiheiheiheiCollaborators
Sep 7 Added label: rfc
Jeremy Qin
Jeremy QinCollaborators
Sep 7 Comments:

👋 您好,欢迎向 MindStudio-Insight 提交 Issue!

我们已收到您的反馈,感谢你对开源社区的支持。🎉

📅 处理时效: 维护团队将在 24 小时内 查看并回复您的问题(工作日)。
🔍 自助查询: 在等待期间,建议您先查阅以下资料,可能已有解决方案:

🚨 紧急联系: 如果您的问题非常紧急,可通过以下方式联系我们:

请确保 Issue 描述清晰,包含复现步骤和日志,这将帮助我们更快定位问题。谢谢!

likedislike
heiheiheiheiheiheiCollaborators
Sep 7 Modify description of issue
heiheiheiheiheiheiCollaborators
Sep 7 Modify description of issue
heiheiheiheiheiheiCollaborators
Sep 7 Modify description of issue
heiheiheiheiheiheiCollaborators
Sep 14 changed custom state from TODO to DONE
heiheiheiheiheiheiCollaborators
Sep 14 Close issue
ascend-robotascend-robotCollaborators
Sep 14 Added label: resolved