Skip to content

Latest commit

 

History

History
453 lines (345 loc) · 18.5 KB

database.md

File metadata and controls

453 lines (345 loc) · 18.5 KB

SnapshotDB Schema

English | 中文

概述

SnapshotDB 是内存快照数据的 SQLite 数据库存储格式,用于持久化内存分配追踪信息。支持多设备(多 GPU)快照数据的存储和查询。 需要说明的是,它不仅仅是将内存快照原始pickle数据转成了SQLite数据库,而是针对原始内存快照数据进行了一次完整的“回放”,并记录了回放过程中的额外信息,如

  1. 任一事件发生后的内存池总大小、总分配内存块大小;
  2. 采集周期中,所有的内存块的完整生命周期(在哪个事件申请、哪个事件释放)

数据库示例文件: snapshot.pkl.db

分析目标包括单库与显式选择的完整已校验原生/兼容数据集;关闭的 compatibility-v1 使用 immutable 只读传输,原生及单库策略仍独立。验收、metadata/frame限制与测量 区分 schema、来源/生命周期差分与待验收 GUI。

生成 SnapshotDB

如果输入是 PyTorch 原始 .pkl 内存快照,可以直接导入:

安全警告: 只能导入可信的 pickle 文件。反序列化 pickle 可能执行任意代码; 实现会拒绝非 builtins 全局对象,但 pt-snap import 不是沙箱。

pt-snap import snapshot.pkl
pt-snap import snapshot.pkl --json

默认情况下,内建快照运行时会在输入文件旁生成 snapshot.pkl.db,并更新当前项目的 focus,后续命令可直接使用:

pt-snap query --list

也可以使用其他兼容生产者生成相同格式的 SnapshotDB,再将生成的 .db 文件传给 pt-snap focus。

导入缓存与 metadata

新生成的数据库包含 pt_snap_metadata 表,记录原始文件 SHA-256、精确设备选择、导入格式 版本、生产者版本和完成时间。只有完整 SHA-256、导入格式版本和设备选择均匹配时,重复导入 才会复用已有 DB;仅升级 pt-snap-cli 包版本不会让缓存失效。

pt-snap overview snapshot.pkl.db
pt-snap overview snapshot.pkl.db --json
pt-snap metadata snapshot.pkl.db
pt-snap metadata snapshot.pkl.db --json
pt-snap import snapshot.pkl --force

import --json 报告 db_path、device_id、reused、cache_miss_reason、 metadata、focus_state 和顶层 focus_source。metadata --json 保持现有字段名(db_path、status、reason、 metadata)以兼容已有调用方。

旧版或外部生成且结构兼容的 DB 仍可查询不依赖可识别调用栈布局的模板。pt-snap 根据表列识别调用栈布局,并把 pt_snap_metadata.import_format_version 当作辅助 校验,而不是唯一依据。调用栈相关模板会自动选择匹配的 SQL。

打开、focus 和查询都不会写入 .db 文件,也不会原地迁移 schema。导入缓存仍会在 当前导入器格式版本不匹配时重建目标库,这与读取兼容是分开的。没有 metadata 时, pt-snap metadata 会报告 unavailable;之后对同一 pickle 再导入会先重建一次再参与 缓存复用。

查询工作流

导入过程会回放分配器事件,并将其规范化为逐设备的 trace_entry_<device> 和 block_<device> 表。Focus 用于选择数据库和可选设备,查询模板再解析对应的设备表名:

pt-snap focus snapshot.pkl.db --device 0
pt-snap query --template-use memory_peak
pt-snap query --template-use block --params '{"min_size": 1048576}'

使用 pt-snap capabilities --json 查看完整模板清单,或用 pt-snap query --list 和 pt-snap query --template-info <name> 查看受支持的 查询入口。event、callstack_analysis 和 active_memory_callstack_at_event 同时支持当前去重调用栈结构和旧版内联文本库;见 调用栈布局兼容。完整流程见运行查询。


数据库结构

表列表

表名 说明 记录数(示例)
dictionary 字典映射表 -
callstack 去重后的调用栈文本,所有设备共享 4,369
trace_entry_0 设备 0 的事件跟踪表 8,094
block_0 设备 0 的内存块表 -
pt_snap_metadata 第一方导入来源与缓存 metadata 1

命名规则: 多设备场景下,表名后缀为设备 ID,如 trace_entry_1、block_1 表示设备 1 的数据。callstack 表没有设备后缀,因为调用栈在设备之间共享。


表详细定义

1. trace_entry_{device} — 事件跟踪表

记录内存管理事件的完整追踪信息。

Schema

CREATE TABLE trace_entry_0 (
    `id` INTEGER PRIMARY KEY,
    `action` INTEGER,
    `address` INTEGER,
    `size` INTEGER,
    `stream` INTEGER,
    `allocated` INTEGER,
    `active` INTEGER,
    `reserved` INTEGER,
    `callstackId` INTEGER
);

字段说明

字段名 类型 约束 说明 示例值
id INTEGER PRIMARY KEY 事件唯一标识,负数表示系统自动生成 1, -100
action INTEGER — 动作类型编码(见下表) 4
address INTEGER — 内存地址 20697535234048
size INTEGER — 分配大小(字节) 41943040
stream INTEGER — 流 ID(CUDA/CANN) 1276474240
allocated INTEGER — 当前已分配总量 136426496
active INTEGER — 当前活跃总量 136426496
reserved INTEGER — 内存池保留总量 155189248
callstackId INTEGER NULL 指向 callstack.id,需 join 才能取到文本 12

动作类型编码(action 字段)

值 名称 说明
0 segment_map 内存段映射(可扩展段)
1 segment_unmap 内存段解除映射
2 segment_alloc 内存段分配
3 segment_free 内存段释放
4 alloc 内存分配事件
5 free_requested 释放请求
6 free_completed 释放完成
7 workspace_snapshot NPU特有的workspace内存池快照

id 字段约束

条件 约束
id >= 0 事件 ID 严格按照启动内存快照采集后的发生顺序递增,且唯一
id < 0 为从原始 pickle 数据中虚拟生成的事件,事件类型一定为 segment_map 或 segment_alloc,用于还原启动内存快照采集时刻已有的 Segment

数据示例

id=1, action=4, address=20697535234048, size=41943040, stream=1276474240
allocated=136426496, active=136426496, reserved=155189248
callstackId=12 -> callstack.callstack:
  /home/liuyekang/dev/projects/test/memory_leaks_demo.py:60 <module>
  /home/liuyekang/dev/projects/test/memory_leaks_demo.py:34 main
  /home/liuyekang/dev/projects/test/memory_leaks_demo.py:24 train
  /home/liuyekang/dev/projects/test/memory_leaks_demo.py:12 train_one_step

读取调用栈文本

join callstack 表解析 callstackId:

SELECT t.id, t.size, c.callstack
FROM trace_entry_0 t
LEFT JOIN callstack c ON c.id = t.callstackId
WHERE t.id = 1;

2. block_{device} — 内存块表

记录内存块的详细信息和生命周期状态。

Schema

CREATE TABLE block_0 (
    `id` INTEGER PRIMARY KEY,
    `address` INTEGER,
    `size` INTEGER,
    `requestedSize` INTEGER,
    `state` INTEGER DEFAULT 99,
    `allocEventId` INTEGER,
    `freeEventId` INTEGER
);

字段说明

字段名 类型 SQL 默认值 说明
id INTEGER — 块唯一标识;动态块使用分配事件 ID,采集开始前已存在的块使用负数 ID
address INTEGER — 内存地址
size INTEGER — 实际分配大小(含对齐开销)
requestedSize INTEGER — 用户请求的大小
state INTEGER 99 状态编码(见下表)
allocEventId INTEGER — 关联的分配事件 ID;未采集到时生产者写入 -1
freeEventId INTEGER — 关联的释放完成事件 ID;未采集到时生产者写入 -1

状态编码(state 字段)

值 名称 说明
-1 inactive 非活跃状态(已释放)
0 active_pending_free 活跃,待释放
1 active_allocated 活跃,已分配
99 unknown 未知状态(默认值)

id 字段约束

条件 约束
id >= 0 block.id 与 allocEventId 一致,共同指向 trace_entry 中相同 ID 的分配事件
id < 0 仅代表通过原始 pickle 数据中的 Segment 信息得知该内存块在采集开始时已分配,无从得知分配时间。负数值本身无实际含义,仅用于唯一标识

allocEventId约束

条件 约束
allocEventId >= 0 block.id 与 allocEventId 一致,共同指向 trace_entry 中相同 ID 的分配事件
allocEventId == -1 代表在内存快照采集期间,未采集到该内存块的申请事件(在开始采集之前该内存块就已经申请分配完成)

freeEventId约束

条件 约束
freeEventId >= 0 指向 trace_entry 中对应的释放完成事件,与 block.id 相互独立
freeEventId == -1 代表在内存快照采集期间,未采集到该内存块的释放完成事件(在结束采集时该内存块并未释放)

state 约束

block.state 仅在 block.id 为负数时才有实际意义,否则无实际用途。

requestedSize 约束

block.requestedSize 是用户请求大小,block.size 是实际分配大小。两者来自快照生产者 或回放后的分配器状态,其关系取决于分配器配置,不能使用单一对齐公式推导。

数据示例

id=-320, address=20697531023360, size=4194816, requestedSize=4194304
state=1, allocEventId=-1, freeEventId=-1

3. dictionary — 字典映射表

存储枚举值的编码映射关系,用于解码 action 和 state 等字段。

Schema

CREATE TABLE dictionary (
    `table` TEXT,     -- 表名
    `column` TEXT,    -- 列名
    `key` TEXT,       -- 编码后的整数值(字符串)
    `value` TEXT      -- 原始字符串值
);

字段说明

字段名 类型 说明
table TEXT 所属表名,如 trace_entry_0、block_0
column TEXT 所属列名,如 action、state
key TEXT 编码后的整数值(字符串格式),如 4、1
value TEXT 原始字符串值,如 alloc、active_allocated

数据示例

table=trace_entry_0, column=action, key=4, value=alloc
table=block_0, column=state, key=1, value=active_allocated

4. callstack — 去重调用栈表

快照中少量调用栈会在极多事件上重复出现,因此文本按不同调用栈只存一份,由 trace_entry_<device>.callstackId 引用。

Schema

CREATE TABLE callstack (
    `id` INTEGER PRIMARY KEY,
    `callstack` TEXT
);

字段说明

字段名 类型 说明
id INTEGER 调用栈 ID,被 trace_entry_<device>.callstackId 引用
callstack TEXT 调用栈文本,最外层帧在前,每行一个 文件:行号 函数名

表属性

属性 保证
唯一性 每组不同的有序结构化帧数组只有一行;显示文本本身不能无损标识调用栈
作用域 数据库内所有设备共享,表名不带设备后缀
覆盖度 导入产生的每个事件都能解析到一行;只有外部生成的数据库才可能出现 callstackId 为 NULL

当前 pt-snap import 保留这种 v2 文本布局,同时增加结构化帧表 (import_format_version = 3)。格式 2 数据库的文本布局相同,但没有原始帧记录。 调用栈去重之前生成的数据库在每张 trace_entry_<device> 表中内联存储 callstack TEXT,没有共享 callstack 表(有 metadata 时为 import_format_version = 1)。

结构化帧与有序数组(格式 3)

frame 对原始 (filename, line, name) 三元组去重;callstack_frame 把调用栈关联到有序的帧 ID 数组:

CREATE TABLE frame (
    id INTEGER PRIMARY KEY,
    filename TEXT NOT NULL,
    line INTEGER NOT NULL,
    name TEXT NOT NULL
);
CREATE TABLE callstack_frame (
    callstackId INTEGER NOT NULL,
    position INTEGER NOT NULL,
    frameId INTEGER NOT NULL
);
CREATE UNIQUE INDEX idx_callstack_frame_position
    ON callstack_frame (callstackId, position);

两张表在设备之间共享。事件通过 trace_entry_<device>.callstackId 关联数组, 按 position ASC 读取即可还原快照原始顺序;位置 0 是最内层帧。帧树分析反向 遍历,从最外层调用者开始。递归中的同一帧保留各自位置,即使帧 ID 相同。 空数组没有关联行。结构化字段直接保留冒号、空白、中文和内嵌换行,无需拆解显示文本。

使用 event_frames 读取事件有序帧,使用 active_memory_frame_tree_at_event 读取各父子节点的占用。详见调用栈帧内存拆解。 旧文本数据库仍可用于原有查询,新查询需要从原始快照重新导入。导入器检测格式变化 后重建缓存;只读分析不会迁移数据库。

单库帧能力边界

格式 3 仅用于单库导入。原生分片导入保持格式 2,兼容导出保持格式 1; 它们通过独立的版本 2 去重帧扩展支持数据集帧树,详见查询指南。新增 callstack_frame_manifest(callstackId INTEGER PRIMARY KEY, frameCount INTEGER NOT NULL) 保存每个采集调用栈的预期长度,包括零。 filename/name 必须是文本,line 必须是整数。event_frames 对缺失、已知空数组 或损坏数组返回零行,不输出部分重建的数组。树将已知空栈与缺失/损坏证据分开。 删除末尾或全部关联、非整数位置以及无效字段类型均不能通过校验。 只读查询不会修复已存储的证据。

调用栈布局兼容

pt-snap 可以读取两种布局,且不会改写数据库文件:

布局 识别方式 调用栈文本
v2(当前导入) trace_entry_<device>.callstackId 加共享 callstack 表 join callstack.id
v1(旧版) trace_entry_<device>.callstack TEXT,无 callstackId,无共享表 直接读该列

event、callstack_analysis 和 active_memory_callstack_at_event 保持相同的 模板名、参数和输出契约。查询引擎按识别到的布局选择 v1 或 v2 SQL。 结构化帧查询额外要求格式 3 的两张帧表,不会从旧显示文本猜测原始帧。

识别过程是只读的:focus、query、报告和 Python API 都以 SQLite mode=ro 打开数据库。布局不会写入 .pt-snap/focus.json。列冲突、设备布局不一致、 损坏的 callstack 表,或 metadata 与物理结构不一致时,布局保持无法识别,并且 只有调用栈模板会报错;不会猜测布局,也不会阻止 focus、metadata 和其他查询。 默认不会做 v1→v2 迁移。

pt-snap focus legacy.db
# Callstack layout: v1 (inline text)
pt-snap query --template-use event
pt-snap query --template-use callstack_analysis

5. pt_snap_metadata — 导入 Metadata 表

第一方导入会创建一条 metadata 记录,用于来源追踪和缓存兼容性检查:

CREATE TABLE pt_snap_metadata (
    id INTEGER PRIMARY KEY CHECK (id = 1),
    metadata_schema_version INTEGER NOT NULL,
    import_format_version INTEGER NOT NULL,
    source_sha256 TEXT NOT NULL,
    source_size INTEGER NOT NULL,
    source_name TEXT NOT NULL,
    requested_device INTEGER,
    importer_name TEXT NOT NULL,
    importer_version TEXT NOT NULL,
    completed_at TEXT NOT NULL
);

旧版或外部生成的兼容数据库可以不包含此表,仍可正常查询;pt-snap metadata 会将其 metadata 状态报告为 unavailable。

已发布原生数据集

import --events-per-slice N 发布独立 pt-snap-native-v2 manifest,不是兼容 v1 manifest,也不改变单库布局。各最终化片使用已有 v2 表及 pt_snap_block_reference (版本 1):blockId INTEGER PRIMARY KEY、stream INTEGER NOT NULL、 allocCallstack TEXT、freeCallstack TEXT。它们记录文本生命周期来源,不是结构化 frames 或自动跨片 JOIN。每片必需且一致的 pt_snap_metadata 之外,原生 manifest 身份另包含源/设备/容量、格式/manifest/导入/扩展合同版本,与 CLI 发布版本分离。

真实计数按各设备位置,保留原始稀疏 ID、OOM/workspace;负边界不占容量。 reader 在有界 event 寻址前校验完整成员哈希、最终化身份/引用一致性,不修复、不迁移。 数据集聚合/生命周期查询仍不支持。详见独立 原生 manifest 协议及 事务恢复指南。 P0 兼容 v1 表序、内联布局和 manifest 语义不变。

显式兼容导出

import --format msinsight(别名 compatibility-v1)生成物理 v1 trace_entry_<device> 表,第九列为 callstack TEXT,不是 VIEW;block/dictionary 位置 schema 精确匹配。转换去除暂存的未隔离 callstack 表,写入 pt_snap_metadata.import_format_version=1,保留隔离的 pt_snap_block_reference 文本生命周期来源。原生数据集保留独立的版本 2 帧扩展,不从文本推断有序 frames。

内联调用栈字节按所有事件的文本总和增长,不按不同栈计数;转换暂时并存原生与内联表, 可能保留 SQLite free pages。容量不限制 block、加载 RSS 或总磁盘。兼容 manifest 的 ptSnap.identity、metadata、省略设备及摘要值为空字符串的结构成员清单随导出写入。 历史摘要字段仅作为清单接受;兼容导入复用检查成员名称、源身份及必要的只读结构, 不比较摘要值,也不扫描任意行内容,因此结构合法的内容编辑可以被复用。 识别到 metadata 不证明数据库内容完整。查询和显式验证器独立执行准入检查; 外部 v1 数据集仍不要求 metadata。原生数据集的内容校验保持不变。

仅最终化兼容数据集的裸校验与缓存分析在首个 SQLite 打开前拒绝全部存活/悬空 sidecar 和别名后使用 mode=ro&immutable=1,保留已关闭/checkpoint 原版 WAL 的字节及 目录清单。前提是无活动 writer;原生数据集非 WAL 策略与单库 mode=ro 默认不变。详见 兼容协议及 no-replace 规则。