English | 中文
SnapshotDB 是内存快照数据的 SQLite 数据库存储格式,用于持久化内存分配追踪信息。支持多设备(多 GPU)快照数据的存储和查询。 需要说明的是,它不仅仅是将内存快照原始pickle数据转成了SQLite数据库,而是针对原始内存快照数据进行了一次完整的“回放”,并记录了回放过程中的额外信息,如
- 任一事件发生后的内存池总大小、总分配内存块大小;
- 采集周期中,所有的内存块的完整生命周期(在哪个事件申请、哪个事件释放)
数据库示例文件: snapshot.pkl.db
分析目标包括单库与显式选择的完整已校验原生/兼容数据集;关闭的 compatibility-v1 使用 immutable 只读传输,原生及单库策略仍独立。验收、metadata/frame限制与测量 区分 schema、来源/生命周期差分与待验收 GUI。
如果输入是 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。
新生成的数据库包含 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 --forceimport --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表没有设备后缀,因为调用栈在设备之间共享。
记录内存管理事件的完整追踪信息。
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 |
| 值 | 名称 | 说明 |
|---|---|---|
| 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 >= 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;记录内存块的详细信息和生命周期状态。
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 |
| 值 | 名称 | 说明 |
|---|---|---|
| -1 | inactive | 非活跃状态(已释放) |
| 0 | active_pending_free | 活跃,待释放 |
| 1 | active_allocated | 活跃,已分配 |
| 99 | unknown | 未知状态(默认值) |
| 条件 | 约束 |
|---|---|
id >= 0 |
block.id 与 allocEventId 一致,共同指向 trace_entry 中相同 ID 的分配事件 |
id < 0 |
仅代表通过原始 pickle 数据中的 Segment 信息得知该内存块在采集开始时已分配,无从得知分配时间。负数值本身无实际含义,仅用于唯一标识 |
| 条件 | 约束 |
|---|---|
allocEventId >= 0 |
block.id 与 allocEventId 一致,共同指向 trace_entry 中相同 ID 的分配事件 |
allocEventId == -1 |
代表在内存快照采集期间,未采集到该内存块的申请事件(在开始采集之前该内存块就已经申请分配完成) |
| 条件 | 约束 |
|---|---|
freeEventId >= 0 |
指向 trace_entry 中对应的释放完成事件,与 block.id 相互独立 |
freeEventId == -1 |
代表在内存快照采集期间,未采集到该内存块的释放完成事件(在结束采集时该内存块并未释放) |
block.state 仅在 block.id 为负数时才有实际意义,否则无实际用途。
block.requestedSize 是用户请求大小,block.size 是实际分配大小。两者来自快照生产者
或回放后的分配器状态,其关系取决于分配器配置,不能使用单一对齐公式推导。
id=-320, address=20697531023360, size=4194816, requestedSize=4194304
state=1, allocEventId=-1, freeEventId=-1
存储枚举值的编码映射关系,用于解码 action 和 state 等字段。
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
快照中少量调用栈会在极多事件上重复出现,因此文本按不同调用栈只存一份,由
trace_entry_<device>.callstackId 引用。
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)。
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第一方导入会创建一条 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 规则。