diff --git a/README.md b/README.md index 67ec7a6..147b326 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,67 @@ [中文文档](README_zh.md) | English -A command-line tool for analyzing PyTorch memory snapshots. Set a snapshot database, run built-in queries, and inspect memory usage, leaks, and timelines. +**High-efficiency, replay-enriched, agent-native CLI and Python toolkit for PyTorch GPU/NPU memory snapshot forensics.** + +`pt-snap-cli` (`pt-snap`) transforms opaque PyTorch memory snapshot `.pkl` dumps into an indexed, relational **SnapshotDB (SQLite)** through a full allocator replay. Inspect peak occupancy, same-event allocator fragmentation, block lifecycles, leak candidates, and interactive frame-level memory flamegraphs in milliseconds—from your terminal, Python scripts, or AI coding agents—without needing PyTorch or a GPU/NPU environment offline. + +```mermaid +flowchart LR + A["PyTorch / TorchNPU
Snapshot (.pkl)"] -->|"pt-snap import
(Allocator Replay)"| B[("SnapshotDB (SQLite)
trace_entry · block
callstack · frame")] + B --> C["13 Parameterized
Query Templates"] + B --> D["Peak & Frame-Tree
Reports (Text / JSON / HTML)"] + B --> E["Agent Skills + CLI
(--json · Zero MCP)"] + B --> F["SnapshotAnalyzer
Python API"] +``` + +## Why `pt-snap`? + +| Dimension | Raw `.pkl` / Ad-hoc Scripts / Static HTML | `pt-snap-cli` (`SnapshotDB`) | +| --- | --- | --- | +| **Efficiency** | Re-parses multi-hundred-MB pickles on every question; heavy browser DOM on large traces | **Import once, query in milliseconds.** Indexed SQLite with SHA-256 cache reuse, read-only `mode=ro` queries, `--timeout` deadlines, and bounded dataset work budgets | +| **Data Structure** | Deeply nested dicts/lists; implicit pool counters and unlinked alloc/free events; repeated inline callstack strings | **Replay-enriched relational schema.** Post-event `allocated`/`active`/`reserved` counters, explicit `allocEventId → freeEventId` block lifecycles, deduplicated `callstack` table, and lossless ordered `(filename, line, name)` `frame` arrays | +| **Analysis Depth** | Visual timeline inspection or custom one-off Python loops | **13 built-in query templates + composite reports.** Same-event `reserved - active` gap analysis, peak callstack attribution with coverage metrics, leak candidate & lifetime buckets, and standalone interactive HTML memory-tree flamegraphs | +| **Agent Readiness** | Raw dumps overflow context windows; unstructured output causes unit/denominator hallucinations | **Agent-native CLI (no MCP server needed).** Deterministic `--json` envelopes, machine-readable `capabilities` & column semantics, `--stack-bytes` token budgeting, honest `has_more`/`truncated` flags, and 6 installable diagnostic skills | + +### 1. High Efficiency — Import Once, Query in Milliseconds + +- **Zero Accelerator Dependency Offline**: Offline import, querying, and reporting require only **Python 3.10+** and standard SQLite—no PyTorch, CUDA, or CANN runtime needed on your analysis machine. +- **Cryptographic Cache Reuse**: `pt-snap import` records source `SHA-256`, import format version, and device selection in `pt_snap_metadata`. Re-importing an unchanged snapshot reuses the validated `.db` in `<1 ms`. +- **Deduplicated Storage**: Callstacks and structured frames are interned once across all devices rather than repeated on every trace event, drastically shrinking disk footprint and scan I/O. +- **Bounded & Predictable Execution**: Every analysis opens SQLite with `mode=ro`, reuses cached connections in `SnapshotAnalyzer`, enforces wall-clock `--timeout` via SQLite progress handlers, and bounds sharded dataset queries with explicit work budgets (`--max-work-rows`, `--max-work-bytes`, `--max-scratch-db-bytes`). + +### 2. Friendlier, Replay-Enriched Data Structure (`SnapshotDB`) + +Instead of dumping raw pickle dictionaries directly into tables, `pt-snap` replays the allocator state machine during import and materializes explicit relational entities: + +| Table | What Replay Materializes | Why It Is Easier to Query | +| --- | --- | --- | +| `trace_entry_` | Chronological events (`alloc`, `free_requested`, `free_completed`, `segment_alloc`, `segment_free`, `segment_map`, `segment_unmap`, `workspace_snapshot`) | Every row carries exact post-event **`allocated`**, **`active`**, and **`reserved`** byte counters plus `callstackId` | +| `block_` | Full memory block lifecycle (`id`, `address`, `size`, `requestedSize`, `state`, `allocEventId`, `freeEventId`) | Instantly join an allocation to its completion event, compare alignment overhead (`size` vs. `requestedSize`), and separate dynamic blocks (`id >= 0`) from preexisting/static blocks (`id < 0`, `allocEventId = -1`) | +| `callstack` | Deduplicated callstack text shared across all devices | Group or filter by `callstackId` without scanning megabytes of repeated stack strings | +| `frame` & `callstack_frame` | Lossless ordered `(filename, line, name)` frame tuples and `position` index (Format 3) | Build exact caller-to-callee memory trees and handle recursive frames or special characters without fragile regex/colon splitting | +| `dictionary` & `pt_snap_metadata` | Self-describing enum key/value mappings and provenance metadata | Portable, self-contained SQLite files that remain compatible across v1 (inline text), v2 (deduplicated text), and v3 (structured frame) layouts | + +### 3. Deep Forensic Analysis Capabilities + +- **Peak Memory & Same-Event Fragmentation (`report peak-memory`)**: Automatically locates independent `allocated`, `active`, and `reserved` peak events, computes **same-event allocator gaps** (`reserved - active` and `reserved - allocated` at the exact peak event instead of misleadingly subtracting peaks from different timestamps), and attributes live blocks to callstacks with explicit `coverage_percent` and `included_bytes`. +- **Frame-Level Live Memory Flamegraphs (`report memory-tree`)**: Decomposes live active memory at any `event_id` into a caller-first frame hierarchy (`size_bytes` inclusive vs. `self_bytes` exclusive). Export to terminal text, JSON, or a **self-contained interactive HTML flamegraph** (`--format html`) with zoom, full-tree search, and keyboard navigation where even tiny or zero-byte frames stay reachable. +- **Lifecycle, Retention & Leak Candidate Forensics**: + - Distinguish unfreed dynamic survivors (`leak_detection`), stream-deferred frees (`free_requested` vs. `free_completed`), and pre-snapshot occupancy (`preexisting_live`). + - Analyze block duration distributions by event-ID distance (`freed_block_lifetime`). +- **Multi-Format & Sharded Scale**: Analyze standalone `.db` files, native sharded datasets (`--events-per-slice`), msinsight-compatible exports (`--format msinsight`), or split multi-device pickles into replay-validated per-device slices (`pt-snap split`). + +### 4. Agent-Native CLI by Design + +`pt-snap` is engineered so AI coding agents (Claude Code, Cursor, Codex, OpenCode, Cline) can diagnose complex OOMs and leaks reliably **without an MCP server**: + +- **Self-Discoverable Contracts**: `pt-snap capabilities --json` and `pt-snap query --template-info --json` expose parameter schemas, `semantics_version`, column `units` (`bytes`, `percent`, `event_id`), `metric_semantics`, `denominator`, `sentinel` (`-1`), and `interpretation_limits`—preventing agents from hallucinating units or denominators. +- **Context-Window Budgeting (`--stack-bytes`)**: Deep PyTorch callstacks quickly exhaust LLM context windows. Passing `stack_bytes` (e.g., `--stack-bytes 256`) returns a UTF-8-safe prefix plus canonical `stack_id`, `stack_truncated`, and `stack_event_id`, allowing the agent to rank hundreds of groups compactly and fetch full stacks via `event(id=stack_event_id)` only for top suspects. +- **Honest Completeness Signals**: Every JSON response reports `total`, `returned`, `has_more`, `truncated`, and `total_is_exact`. Agents know immediately when a `LIMIT` or `top_n` window is partial and can widen the window or pass `--exact-total`. +- **Strict Parameter Validation & Error Envelopes**: Misspelled parameters (e.g., `min_sze`) fail fast with `INVALID_PARAMETER` and accepted keys instead of silently running unfiltered SQL. On `--json` failure, `stdout` stays empty while `stderr` emits a structured error object with `code`, `message`, and actionable `hint`. +- **6 Bundled Agent Skills**: Installable in one command (`pt-snap skill install`) to guide agents through read-only preflight, bounded evidence gathering, and output recovery. + +--- ## Start Here @@ -43,6 +103,12 @@ pt-snap query snapshot.pkl.db --device 0 --template-use memory_peak --json pt-snap report peak-memory snapshot.pkl.db --device 0 --metric active --limit 20 ``` +Generate an interactive HTML frame-level memory flamegraph at the peak event (for example, event `100`): + +```bash +pt-snap report memory-tree snapshot.pkl.db --device 0 --event-id 100 --format html > memory-tree.html +``` + Default import writes `snapshot.pkl.db` beside the pickle and updates project `.pt-snap/focus.json` in the current directory. Add `--no-focus` to avoid that focus change, not to prevent DB replacement: a standalone cache miss/`--force` @@ -58,6 +124,28 @@ byte units, allocated/active/reserved counters, expected output and partial repo - [Replayable pickle splitting](docs/en/splitting.md): one split strategy and a new output directory; separate from dataset import. - [Complete-dataset addressing](docs/en/sharded-snapshotdb.md#complete-dataset-focus-and-addressing-p1), [global built-in support](docs/en/querying.md#dataset-global-built-in-support-p3), and [recorded interoperability acceptance](docs/en/interop-acceptance.md): advanced contracts and evidence, not prerequisites for a first report. +## Built-in Query Templates & Reports + +Use `pt-snap query --list` or `pt-snap capabilities --json` to inspect all 13 built-in templates and their parameter/output schemas: + +| Category | Template / Command | Purpose | +| --- | --- | --- | +| **Basic** | `event` | Filter trace events by ID bounds, action code, size, stream, or compact `stack_bytes` | +| **Basic** | `block` | Filter memory blocks by size, state, address, or lifecycle event bounds | +| **Basic** | `allocation` | Query `(id, allocated, active, reserved)` timeline trajectory | +| **Basic** | `event_frames` | Read the ordered `(position, filename, line, name)` frame array for a specific event (Format 3) | +| **Statistical** | `memory_peak` | Independent `allocated`, `active`, and `reserved` maxima and earliest peak event IDs | +| **Statistical** | `allocator_gap` | Peak events plus same-event `reserved - active` and `reserved - allocated` fragmentation gaps | +| **Statistical** | `active_blocks_at_event` | Enumerate blocks live at `event_id` (`allocEventId <= E < freeEventId` or unfreed), with optional static/preexisting blocks | +| **Statistical** | `callstack_analysis` | Aggregate count, total/min/max/average size across all stack-bearing trace actions | +| **Business** | `active_memory_callstack_at_event` | Group active memory at `event_id` by allocation callstack with byte share percentages | +| **Business** | `active_memory_frame_tree_at_event` | Caller-first tree breakdown (`size_bytes` inclusive vs. `self_bytes` exclusive) at `event_id` | +| **Business** | `leak_detection` | Find dynamic blocks allocated during capture that never recorded a `free_completed` event | +| **Business** | `preexisting_live` | Summarize pre-capture blocks (`allocEventId = -1`) still live at `event_id` | +| **Business** | `freed_block_lifetime` | Bucket completed block lifecycles by `freeEventId - allocEventId` event distance | +| **Report** | `report peak-memory` | One-shot `allocator_gap` + `active_memory_callstack_at_event` with coverage and completeness metadata | +| **Report** | `report memory-tree` | Text, JSON, or self-contained interactive HTML flamegraph of live memory by call frame | + ## Commands | Command | Description | @@ -96,13 +184,30 @@ deep-pagination costs and all-or-error semantics. ## Agent Skills +Install bundled diagnostic workflows with `pt-snap skill install`. Agent integration uses skills plus the CLI; there is no MCP server. See the [Agent Skills guide](docs/en/skills.md). + +```bash +# Install bundled skills for shared Agent Skills hosts (~/.agents/skills) and Claude Code (~/.claude/skills) +pt-snap skill install + +# Verify installation status as machine-readable JSON +pt-snap skill list --json +``` + +| Bundled Skill | Role | +| --- | --- | +| `pt-snap-helper` | Entry router: inspects user goal and input type, runs `capabilities` + `overview` preflight, and dispatches to the right workflow | +| `pt-snap-setup` | Verifies or installs `pt-snap-cli` in the active Python environment with shebang/interpreter ownership checks | +| `pt-snap-ascend-npu-collect` | Guides Ascend NPU memory snapshot `.pkl` capture (works even before `pt-snap` CLI is installed) | +| `pt-snap-memory-peak-breakdown` | Explains active memory at peak events, callstack attribution, and static/preexisting occupancy | +| `pt-snap-memory-leak` | Diagnoses end-of-trace unfreed dynamic candidates vs. pending frees and preexisting memory | +| `pt-snap-memory-fragmentation` | Investigates `reserved - active` allocator gaps, `segment_map`/`segment_unmap` behavior, and pool pressure | + For long diagnostic stacks, opt into `stack_bytes` on `event` or `active_memory_callstack_at_event`, or `report peak-memory --stack-bytes 256`. See [compact callstack text](docs/en/querying.md#compact-callstack-text) for identity, byte-budget metadata and full-text retrieval. -Install bundled diagnostic workflows with `pt-snap skill install`. Agent integration uses skills plus the CLI; there is no MCP server. See the [Agent Skills guide](docs/en/skills.md). - Ascend NPU capture can proceed without `pt-snap` when the host has loaded `pt-snap-ascend-npu-collect`; the helper routes collection before CLI setup. Analysis still requires the CLI and a SnapshotDB, with trusted import as a separate decision. diff --git a/README_zh.md b/README_zh.md index 922c33c..3e824c1 100644 --- a/README_zh.md +++ b/README_zh.md @@ -7,7 +7,67 @@ 中文文档 | [English](README.md) -用于分析 PyTorch 内存快照的命令行工具。设置快照数据库,运行内置查询,检查内存使用、泄漏和时间线。 +**面向 PyTorch GPU/NPU 内存快照诊断的高效、重放增强型、Agent 原生命令行与 Python 工具集。** + +`pt-snap-cli`(`pt-snap`)通过完整的分配器状态机重放(Allocator Replay),将晦涩的 PyTorch 原始内存快照 `.pkl` 转换为带索引的关系型 **SnapshotDB(SQLite)**。无需在分析机上安装 PyTorch 或 GPU/NPU 驱动,即可在毫秒级完成峰值内存归因、同事件碎片化差距(`reserved - active`)诊断、内存块完整生命周期追踪、泄漏候选筛查以及交互式调用栈帧火焰图生成——无论是在终端、Python 脚本还是 AI 编程 Agent 中。 + +```mermaid +flowchart LR + A["PyTorch / TorchNPU
原始快照 (.pkl)"] -->|"pt-snap import
(分配器重放)"| B[("SnapshotDB (SQLite)
trace_entry · block
callstack · frame")] + B --> C["13 个参数化
内置查询模板"] + B --> D["峰值归因与帧内存树
报告 (Text / JSON / HTML)"] + B --> E["Agent Skills + CLI
(--json · 零 MCP 依赖)"] + B --> F["SnapshotAnalyzer
Python API"] +``` + +## 为什么选择 `pt-snap`? + +| 维度 | 原始 `.pkl` / 临时脚本 / 静态大网页 | `pt-snap-cli`(`SnapshotDB`) | +| --- | --- | --- | +| **高效性** | 每次提问都要重新反序列化数百 MB 的 pickle;超大轨迹下浏览器 DOM 极易卡顿 | **一次导入,毫秒级查询。** SQLite 索引加速 + SHA-256 缓存复用(命中 `<1 ms`)、只读 `mode=ro` 连接、`--timeout` 进度中断与显式数据集工作预算 | +| **数据结构** | 深层嵌套字典/列表;内存池水位隐式变化、申请与释放事件未关联、长调用栈重复存储 | **重放增强的关系型模型。** 每个事件后精确记录 `allocated`/`active`/`reserved` 水位,显式构建 `allocEventId → freeEventId` 块生命周期,跨设备去重 `callstack`,无损保留有序 `(filename, line, name)` 结构化帧(`frame`) | +| **分析能力** | 仅靠肉眼拖拽时间线,或每次手写一次性 Python 遍历逻辑 | **13 个内置查询模板 + 高阶组合报告。** 支持同事件 `reserved - active` 碎片分析、带覆盖率的峰值调用栈归因、泄漏候选与生命周期分桶、单文件交互式 HTML 内存帧火焰图 | +| **Agent 友好** | 原始输出瞬间撑爆上下文窗口;缺少字段单位与分母约定易引发大模型幻觉 | **专为 Agent 设计的 CLI(无需 MCP Server)。** 确定性 `--json` 信封、可自发现的 `capabilities` 与字段语义契约、`--stack-bytes` 上下文预算控制、诚实的 `has_more`/`truncated` 完整性标记,以及 6 个随包诊断 Skill | + +### 1. 高效:一次重放导入,毫秒级受控查询 + +- **离线分析零加速器依赖**:离线导入、查询与报告仅需 **Python 3.10+** 与标准 SQLite,分析环境无需安装 PyTorch、CUDA 或 CANN。 +- **哈希校验缓存复用**:`pt-snap import` 在 `pt_snap_metadata` 中记录源文件 `SHA-256`、导入格式版本及设备选择;未发生变化的快照重复导入时在 `<1 ms` 内直接复用。 +- **跨设备调用栈与帧去重**:海量事件共享少量调用栈与代码帧,`callstack` 与 `frame` 表仅存储唯一条目并通过整数 ID 关联,显著降低磁盘占用与扫描开销。 +- **严格只读与资源边界**:所有分析均以 `mode=ro` 打开 SQLite,支持 SQLite progress handler 驱动的 `--timeout` 超时控制,以及面向分片数据集的显式工作上限(`--max-work-rows`、`--max-work-bytes`、`--max-scratch-db-bytes`)。 + +### 2. 更友好的数据结构:分配器重放构建的 `SnapshotDB` + +`pt-snap` 并非简单地把 pickle 字典平铺进数据库,而是在导入阶段完整重放内存分配器状态机,提炼出直观、易查询的关系表: + +| 数据表 | 重放阶段构建的核心信息 | 为什么对分析更友好 | +| --- | --- | --- | +| `trace_entry_` | 按时序排列的分配器动作(`alloc`、`free_requested`、`free_completed`、`segment_alloc`、`segment_free`、`segment_map`、`segment_unmap`、`workspace_snapshot`) | 每条事件直接附带该时刻之后的精确 **`allocated`**、**`active`**、**`reserved`** 字节水位与 `callstackId` | +| `block_` | 内存块完整生命周期(`id`、`address`、`size`、`requestedSize`、`state`、`allocEventId`、`freeEventId`) | 直接关联某次分配何时释放、对比对齐损耗(`size` vs `requestedSize`),并清晰区分采集中动态分配块(`id >= 0`)与采集前已存在的存量/静态块(`id < 0`, `allocEventId = -1`) | +| `callstack` | 跨设备共享的去重调用栈文本 | 按 `callstackId` 高效聚合,无需反复扫描重复字符串 | +| `frame` & `callstack_frame` | 无损有序的 `(filename, line, name)` 结构化帧元组与 `position` 序号(Format 3) | 直接构建从外层调用者到内层分配点的内存占比树,妥善处理递归帧与特殊字符,无需脆弱的冒号/换行文本切分 | +| `dictionary` & `pt_snap_metadata` | 自描述的枚举值映射字典与来源校验元数据 | 单文件自包含,同时无感兼容 v1(内联文本)、v2(去重文本)和 v3(结构化帧)数据库布局 | + +### 3. 深度分析能力:从宏观水位到逐帧火焰图 + +- **峰值归因与同事件碎片差距(`report peak-memory`)**:独立定位 `allocated`、`active`、`reserved` 各自的峰值事件,计算**同一事件时刻**的 `reserved - active` 与 `reserved - allocated` 差距(避免将不同时刻的峰值直接相减产生误导),并按调用栈归因存活内存及输出 `coverage_percent` 与 `included_bytes`。 +- **逐帧存活内存树与交互式火焰图(`report memory-tree`)**:在任意 `event_id` 将存活内存按调用链拆解为包含子节点占用(`size_bytes`)与自身终点占用(`self_bytes`),支持输出终端文本、JSON 或**零服务端依赖的单文件交互式 HTML 火焰图**(`--format html`),内置全树搜索与键盘导航,极小或零字节帧也可直达。 +- **生命周期、延迟释放与泄漏候选分析**: + - 区分采集中未完成释放的动态块(`leak_detection`)、流同步前挂起释放的块(`free_requested` 但未 `free_completed`)以及采集前存量块(`preexisting_live`)。 + - 按 `freeEventId - allocEventId` 事件跨度统计已释放块的生命周期分布(`freed_block_lifetime`)。 +- **多形态数据支持**:支持独立 `.db` 单库、原生分片数据集(`--events-per-slice`)、msinsight 兼容数据集导出(`--format msinsight`)以及按设备/切片的可回放 pickle 拆分(`pt-snap split`)。 + +### 4. 原生 Agent 友好的命令行设计 + +`pt-snap` 从底层交互协议上为 Claude Code、Cursor、Codex、OpenCode、Cline 等 AI Agent 量身定制,**无需额外部署 MCP Server**: + +- **契约自发现(防幻觉)**:`pt-snap capabilities --json` 与 `pt-snap query --template-info --json` 完整输出参数类型/枚举、语义版本(`semantics_version`)、输出列单位(`bytes`、`percent`、`event_id`)、分母含义(`denominator`)、哨兵值(`-1`)及解读边界(`interpretation_limits`)。 +- **上下文窗口预算控制(`--stack-bytes`)**:深度学习调用栈往往极长;通过 `--stack-bytes 256` 可按 UTF-8 安全边界截断调用栈文本,同时保留唯一身份 `stack_id`、`stack_truncated` 与定位事件 `stack_event_id`,让 Agent 先低成本扫描全局排名,再对关键嫌疑项按需拉取完整调用栈。 +- **诚实的完整性信号**:所有 `--json` 查询与报告均包含 `total`、`returned`、`has_more`、`truncated` 与 `total_is_exact`,防止 Agent 将受 `LIMIT` 或 `top_n` 截断的局部窗口误判为全量数据。 +- **严格参数校验与结构化错误信封**:拼写错误的参数(如 `min_sze`)会立即触发 `INVALID_PARAMETER` 并提示合法参数名,绝不静默退化为无过滤全表查询;`--json` 失败时 `stdout` 保持为空,`stderr` 输出带 `code`、`message`、`hint` 的标准 JSON 错误对象。 +- **随包内置 6 个诊断 Skill**:一行 `pt-snap skill install` 即可将标准化预检、有界取证与截断恢复工作流安装到主流 Agent 宿主目录。 + +--- ## 从这里开始 @@ -42,6 +102,12 @@ pt-snap query snapshot.pkl.db --device 0 --template-use memory_peak --json pt-snap report peak-memory snapshot.pkl.db --device 0 --metric active --limit 20 ``` +在指定事件(例如事件 `100`)生成按调用栈帧拆解的交互式 HTML 内存火焰图: + +```bash +pt-snap report memory-tree snapshot.pkl.db --device 0 --event-id 100 --format html > memory-tree.html +``` + 默认导入在 pickle 旁写出 `snapshot.pkl.db`,并更新当前目录的项目 `.pt-snap/focus.json`;加 `--no-focus` 只避免 focus 变化,不防止 DB 替换:单库缓存 未命中或 `--force` 可能替换同名 DB,必要时选择其他 `--output-dir`。显式路径的检查/查询/报告 @@ -55,6 +121,28 @@ allocated/active/reserved 指标、预期输出和报告不完整的情况。 - [可回放 pickle 拆分](docs/zh/splitting.md):只选一种拆分策略并使用新目录,与数据集导入不同。 - [完整数据集寻址](docs/zh/sharded-snapshotdb.md#完整数据集-focus-与寻址p1)、[全局内建支持](docs/zh/querying.md#数据集全局内建支持p3)和[已记录的互操作验收](docs/zh/interop-acceptance.md):按需查看高级合同与证据,不是第一份报告的前置条件。 +## 内置查询模板与报告 + +可执行 `pt-snap query --list` 或 `pt-snap capabilities --json` 查看全部 13 个内置查询模板及其参数与输出契约: + +| 分类 | 模板 / 命令 | 用途说明 | +| --- | --- | --- | +| **Basic** | `event` | 按事件 ID 范围、动作码、大小、流或紧凑 `stack_bytes` 过滤分配器事件 | +| **Basic** | `block` | 按块大小、状态码、地址或分配/释放事件范围检索内存块 | +| **Basic** | `allocation` | 查询 `(id, allocated, active, reserved)` 内存水位时间线 | +| **Basic** | `event_frames` | 读取指定事件的有序 `(position, filename, line, name)` 结构化调用栈帧(Format 3) | +| **Statistical** | `memory_peak` | 获取 `allocated`、`active`、`reserved` 各自的最大值及最早达到峰值的事件 ID | +| **Statistical** | `allocator_gap` | 对比三类峰值事件,并计算同一事件时刻的 `reserved - active` 与 `reserved - allocated` 碎片差距 | +| **Statistical** | `active_blocks_at_event` | 列出在 `event_id` 时刻仍存活的内存块(`allocEventId <= E < freeEventId` 或未释放),可选包含静态/存量块 | +| **Statistical** | `callstack_analysis` | 按调用栈聚合全部带栈事件的数量、总字节、最小/最大/平均大小 | +| **Business** | `active_memory_callstack_at_event` | 将 `event_id` 时刻的存活内存按分配调用栈聚合,计算字节占比 | +| **Business** | `active_memory_frame_tree_at_event` | 在 `event_id` 时刻按外层调用者优先构建逐帧内存树(含子树汇总 `size_bytes` 与本帧终点 `self_bytes`) | +| **Business** | `leak_detection` | 查找采集期间动态分配且直到结束仍未记录 `free_completed` 的泄漏候选块 | +| **Business** | `preexisting_live` | 统计采集开始前已分配(`allocEventId = -1`)且在 `event_id` 时刻仍存活的内存占用 | +| **Business** | `freed_block_lifetime` | 按 `freeEventId - allocEventId` 事件跨度对已完成释放的内存块进行生命周期分桶 | +| **Report** | `report peak-memory` | 一键组合 `allocator_gap` + `active_memory_callstack_at_event`,附带覆盖率与完整性元数据 | +| **Report** | `report memory-tree` | 输出指定事件时刻的终端文本树、JSON 树或单文件交互式 HTML 内存帧火焰图 | + ## 命令 | 命令 | 说明 | @@ -91,12 +179,29 @@ included bytes 为分母。解读有上限的分组结果前,请参阅 ## Agent Skills +使用 `pt-snap skill install` 安装随包诊断工作流。Agent 集成入口是 skills 与 CLI,不再提供 MCP 服务器。详见 [Agent Skills 指南](docs/zh/skills.md)。 + +```bash +# 安装随包 Skill 到通用 Agent Skills 目录(~/.agents/skills)与 Claude Code 目录(~/.claude/skills) +pt-snap skill install + +# 以机器可读 JSON 检查安装状态 +pt-snap skill list --json +``` + +| 随包 Skill | 职责说明 | +| --- | --- | +| `pt-snap-helper` | 诊断总入口路由:根据用户目标与输入类型完成 `capabilities` + `overview` 预检,并分发至对应子工作流 | +| `pt-snap-setup` | 在当前 Python 环境中验证或安装 `pt-snap-cli`,校验 shebang 与解释器归属一致性 | +| `pt-snap-ascend-npu-collect` | 指导昇腾 NPU 内存快照 `.pkl` 采集(宿主已加载该 Skill 时无需预先安装 `pt-snap` CLI) | +| `pt-snap-memory-peak-breakdown` | 诊断峰值事件时刻的存活内存构成、调用栈归因及静态/存量内存占比 | +| `pt-snap-memory-leak` | 排查轨迹末尾未释放的动态分配候选块,区分挂起释放(pending free)与采集前存量块 | +| `pt-snap-memory-fragmentation` | 诊断 `reserved - active` 分配器差距、`segment_map`/`segment_unmap` 行为与内存池膨胀压力 | + 诊断长调用栈时,可在 `event` 或 `active_memory_callstack_at_event` 上显式设置 `stack_bytes`,或使用 `report peak-memory --stack-bytes 256`。 身份、字节预算元数据及完整文本检索方式见[紧凑调用栈文本](docs/zh/querying.md#紧凑调用栈文本)。 -使用 `pt-snap skill install` 安装随包诊断工作流。Agent 集成入口是 skills 与 CLI,不再提供 MCP 服务器。详见 [Agent Skills 指南](docs/zh/skills.md)。 - 宿主已加载 `pt-snap-ascend-npu-collect` 时,没有 `pt-snap` 也能进行昇腾 NPU 采集; helper 会先路由采集,无需先安装 CLI。分析仍需要 CLI 和 SnapshotDB,可信导入是独立决定。