Skip to content

Ascend/msagent / skills/profiler/memory-analysis

memory-analysis

Verified

对 msMemScope 显存数据做全链路处理:根据用户的显存问题诉求(OOM、显存泄漏、显存占比拆解、Step 间对比等),指导并帮助用户以最合适的 msMemScope 采集配置完成显存数据采集(支持命令行、Python 接口、mstx 打点三种采集方式,覆盖训练、推理 vLLM-Ascend、FSDP、强化学习 verl 等场景);对已采集的 memscope_dump_*.csv/db 数据做系统性解读与问题诊断(整体显存曲线趋势分析、显存使用大头按模块/组件拆解分析、显存峰值点各模块与流程占比分析,以及对显存泄漏、OOM 等典型问题的根因定位与原因分析)。

references/leak_diagnosis_guide.md

View on GitHub
# 显存泄漏诊断指南(检测方法 + 模式对照)

> 用途:**进行泄漏判定与归因的完整方法**。判定用 §1~§4;定位出泄漏点后对照 §5 模式库给出原因假设;复采验证用 §7。泄漏模式是**假设而非定论**,须经验证路径确认。
> 相关:数据字段与口径见 `msmemscope_data.md`(shadow 键 §2.1、统计键 §3);曲线/抽样口径见 `msmemscope_data.md` §3/§4;PTA 池行为(释放≠归还、流池)见 `pta_memory_management.md` §2/§3。

## 1. 幽灵机制:为什么"MALLOC/FREE 配对"不是无泄漏证据(必读)

msmemscope 的幽灵(shadow)机制(行为链,源码 `event_router.cpp`):

1. **非采集期(stop 状态)发生的事件标记 `shadow:true`**——该期间申请的内存块标记 SHADOW_CREATED,释放标记 shadow FREE;
2. **阴影分配 + 阴影释放 = 直接消亡不留事件**:start 前申请、stop 期间释放的块在 dump 中完全无痕;
3. **非采集期释放(采集窗口内申请的块)→ shadow FREE 事件,时间戳被刷为"最后一次 stop + 1"**;
4. **进程退出(PROC_EXIT)/ 地址复用(RESIDUAL_BLOCK)时仍未释放的块 → 工具补发 shadow FREE**(PROC_EXIT 且 stopTs>0 时时间戳同样 = stopTs + 1)。

**推论**:

- dump 中**每条 MALLOC 必有配对 FREE(真实或 shadow)**——用"MALLOC 无 FREE"找泄漏必然失败;
- 泄漏判定的正确口径是:**该 Ptr 的 FREE 是否全部为 `shadow:true`**(即采集窗口内无真实 FREE)。

## 2. 泄漏点识别(基于 dump 数据)

1. **找出采集窗口内申请、至窗口结束未真实释放的内存块**:同一 Ptr 的 FREE 记录全部为 `shadow:true`(采集窗口内无真实 FREE)。
2. **提取泄漏块的证据**:`size`(泄漏量)、`owner`(模块归属)、`Call Stack(Python)`/`Call Stack(C)`(申请位置)、所属 `step`/`kernel`(泄漏时机)。
3. **汇总泄漏规模**:按 owner/调用栈聚合泄漏总量,判断主泄漏点(TOP)。

## 3. 算法化检测与风险分级

基于 msmemscope 事件流(先执行第 4 节"判别注意"的前置规则):

- **算法 A(活跃块增长检测,泄漏强信号)**:池 `used` 序列在每个运行周期(Step/批次)结束后不回落到该周期基线、整体单调上升 → 块级不释放。判定:取各周期结束时刻的池 `used`(PTA/MindSpore/ATB),检查序列是否单调上升(第一 Step 剔除)。**已脚本化**:`--trend --pool <池>` 按等宽时间桶输出桶末 used(剔除第 1 桶为基线)+ 单调性/不回基线判定。
- **算法 B(预留增长检测,弱信号)**:池 `total` 或 HAL 段申请序列单调非减且无回落 → 池预留持续增长。⚠️ 池 total 只增不减是框架"释放≠归还"的正常行为(见 `pta_memory_management.md` §2.2),**该信号不能单独作为泄漏证据**,必须与算法 A 联动(A 未命中时优先解释为工作集增长/池缓存)。**已脚本化**:`--trend` 输出 total 桶末单调性、`--fragmentation --pool <池>` 输出逐次扩容清单(扩容前 used/total 有效使用率)。
- **算法 C(长生命周期检测)**:申请时间在采集时间线前 20% 内、至采集结束仍无**真实(非 shadow)FREE** 的块(同一 Ptr 的全部 FREE 均为 `shadow:true`),统计数量与累计大小——**已脚本化**:`python3 scripts/aggregate_dump.py <dump.csv> --leak-candidates [--detail N]` 一键筛选"无真实释放"的候选块(FREE 全部为 shadow:true / 无任何 FREE 事件),按 owner、一级归口、申请时间跨度、Call Stack 首帧聚合,`--detail` 输出候选块明细(Ptr/大小/申请时间/最后 shadow FREE 时间/次数/调用栈);推荐先跑脚本筛候选,再结合第 4 节 shadow 来源区分,剔除非采集期正常释放(多轮 start/stop 时挂在中间 stop 点之后的 shadow FREE)。
- **算法 D(堆栈归因)**:按 Call Stack 聚合算法 C 命中的块:累计大小、块数、占比,TOP 3 为泄漏嫌疑,输出关键路径。

**风险分级**(阈值为启发式,按数据规模/Step 数调整):

- 高风险:算法 A 命中且长寿块 ≥5;或 used 每周期不回基线且增长量显著(如 ≥1 个周期分配量的均值)
- 中风险:算法 A 或 B 命中,或长寿块 ≥3
- 低风险:无明显增长趋势且长寿块 <3

## 4. 判别注意

- **核心结论:MALLOC/FREE 一定一一配对,配对不是无泄漏证据**(机制见第 1 节)——泄漏判定必须看"该 Ptr 的 FREE 是否全部为 shadow"。
- **幽灵释放(attr `shadow:true`)需区分来源**:其一为**非采集期正常释放**——工具处于 stop 状态时内存正常释放,释放事件也被标记 `shadow:true`,对应真实的释放行为;其二为**进程退出时统一释放**——退出时仍未释放的内存由工具统一生成 shadow FREE(stop 状态退出时时间戳 = 最后一次 stop 事件时间 + 1,start 状态退出时时间戳 ≈ 进程退出时刻),这才是**一般意义上的未释放内存**。注意:**两类 shadow FREE 的时间戳都可能落在 stop+1 处(源码将非采集期释放事件时间戳也刷为 stop+1),不能单凭时间戳区分**;实用判别——多轮 start/stop 时,挂在**中间 stop 点之后**的 shadow FREE 多为非采集期正常释放(可核对后续 start 后对应块不再存活),挂在**最后一次 stop/退出时刻**的以"退出补齐"(未释放)为主;单轮采集(一次 start 到进程退出)时全部 shadow FREE 均可视为泄漏候选,再按算法 A/B 的增长性判别。
- **常驻内存 ≠ 泄漏**:未正常释放的内存可能是常驻内存(一般在程序前期申请、总量稳定),也可能是泄漏(常见周期性增长);以增长性判别,不要把常驻内存误判为泄漏。
- **第一 Step 波动不算泄漏**:内存尚未稳定,从第二 Step 起分析(在线泄漏分析本身即如此)。
- **历史存量不参与**:start 前的存量显存只参与统计(总量准确),不参与泄漏/拆解分析。
- **单条小规模遗留不一定是泄漏**:单条小泄漏(如每 Step 数百字节)也可能是正常的池管理噪声,以**持续增长**为判据,不要对瞬时现象下结论。

## 5. 常见泄漏模式对照

> 使用方法:识别出泄漏点(未释放内存块的 size/owner/Call Stack/step 信息)后,对照下表匹配模式,给出原因假设与验证路径。匹配到的模式是假设而非定论,验证路径通过后才能下结论。

### 5.1 模型/推理缓存未清理

- **现象特征**:曲线阶梯式持续攀升;泄漏 owner 集中在推理框架缓存(如 `kv_cache` 增长、中间结果缓存);泄漏块 Call Stack 指向推理循环内的缓存逻辑。
- **常见场景**:推理服务长稳运行,beam search/生成循环中缓存未随轮次清理;vLLM kv_cache 配置过大或未复用。
- **验证路径**:核对 dump 中泄漏块 owner 与 Call Stack 是否集中在缓存管理代码;对比不同 batch/序列长度下泄漏速率是否成正比。
- **修复方向**:缓存复用/及时释放;限制 kv_cache 大小;推理循环结束后显式清理。

### 5.2 梯度 / 优化器状态累积

- **现象特征**:泄漏块 owner 为 `gradient` 或 `optimizer_state`;曲线随 Step 数线性增长;泄漏量 ≈ 每 Step 梯度大小 × 次数。
- **常见场景**:`optimizer.step()` 未正确调用导致梯度累积未释放;梯度累加(gradient accumulation)配置下中间状态未释放;自定义训练循环中每 Step 新建优化器状态。
- **验证路径**:按 Step 聚合泄漏块数量/大小,看是否线性增长且增长量匹配梯度/优化器状态尺寸。
- **修复方向**:检查训练循环的 optimizer.zero_grad/step 配对;确认梯度累积实现正确。

### 5.3 KV cache 随序列长度增长

- **现象特征**:推理场景泄漏量随生成序列长度增长;owner 为 `kv_cache` 相关。
- **常见场景**:长上下文生成时 KV cache 预留与释放策略不当;多头缓存未按实际长度释放。
- **验证路径**:核对泄漏时刻与序列长度增长的相关性。
- **修复方向**:调整 KV cache 预分配/复用策略;控制上下文长度。

### 5.4 循环内重复申请未释放

- **现象特征**:泄漏块 Call Stack 指向同一代码位置(循环体内);泄漏数量 = 循环次数 × 每次申请量;曲线呈等步长锯齿上升(申请多、释放少)。
- **常见场景**:循环中每轮创建 Tensor/临时结果未释放;batch 循环内缓存 dict 持续 append。
- **验证路径**:统计同一 Call Stack 下未释放块数量,与循环次数比对。
- **修复方向**:循环内复用缓冲;循环结束清理。

### 5.5 Python 侧引用残留导致内存池残留

- **现象特征**:泄漏块 owner 为 PTA 池;Call Stack(Python) 指向模块级/全局引用;曲线在长时间运行后整体上移。
- **常见场景**:全局变量/模块级缓存持有 Tensor 引用;闭包捕获导致引用不释放;dataloader 预取缓存残留。
- **验证路径**:检查泄漏块 Call Stack(Python) 指向的引用持有点;Python 侧 `gc.collect()` 后是否释放(注意:显存池回收可能延迟,需区分池预留与真实泄漏)。
- **修复方向**:解除全局引用;使用后 del + 释放;限制缓存大小。
- **机制根源**:PTA 池 used 平台期不是"没释放"而是"没触发释放";`gc.collect()` 可强制回收循环引用(见 `pta_memory_management.md` §2/§3)。

### 5.6 中间 Tensor 生命周期不当(临时闲置演化为泄漏)

- **现象特征**:`aten` owner 的块申请后长期不释放;算子图融合/重计算场景中间结果缓存。
- **常见场景**:重计算(activation checkpointing)实现中中间激活未释放;动态图下中间 Tensor 生命周期被意外延长。
- **验证路径**:核对 `aten` 块从申请到释放的时间跨度与代码逻辑。
- **修复方向**:显式释放中间量;优化重计算实现。

### 5.7 驱动/框架版本问题(伪泄漏)

- **现象特征**:曲线显示"泄漏",但 owner 为 HAL、泄漏块无 Python 调用栈(call stack 为空)、或与任务结束后的整卡残留一致。
- **说明**:可能是框架池预留在 Step 边界间的正常行为(池预留不释放),或驱动侧保留块(如 workspace 缓存),**不是真泄漏**。
- **验证路径**:对照 `npu-smi info` 整卡用量(进程结束后是否回落);检查内存池 total(预留)vs used(实际使用)差异。
- **处理**:区分"池预留"(total 高、used 低、不增长)与"真泄漏"(used 持续增长)。

## 6. 与 ascend-npu-snapshot-analyzer 的差异

该 skill 的单调增长算法用"段 alloc/free 计数"推断、长生命周期用"块状态为 active_allocated 且段创建事件在时间线前 20%"判定;msmemscope 无段级/块级存量视图,用池 used/total 曲线与事件配对等价实现——**used 曲线是块级信号、更直接**;其依赖的段级块状态(active_pending_free 等)msmemscope 不可得,深度归因可引用该 skill 补采 `_dump_snapshot`。

## 7. 泄漏相关采集配置(复采验证用)

| 场景 | 配置 | 说明 |
| --- | --- | --- |
| 在线泄漏分析 | `--analysis=leaks` + `--events=alloc,free` | 采集结束回显逐卡泄漏汇总 + 内存波动 |
| 离线泄漏分析 | mstx mark A/B/C 打点 + 事后 `check_leaks(input_path=..., mstx_info=...)` | A→B 范围申请、C 点前未释放即判定泄漏 |
| 泄漏归因到代码位置 | `--call-stack=python:N,c:M` | 无调用栈时只能定位分配行为,无法给出代码位置 |
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexVerifiedInstall