DeviceStats

torch.cuda.memory_stats()返回的
对应到torch c这一层是_cuda_memoryStats，THCPModule_memoryStats，getDeviceStats
统计信息包含下面的列表：

```C++
struct DeviceStats {
StatArray allocation; // 用户层 malloc 次数
StatArray segment; // 物理段（cudaMalloc/cuMemCreate）次数
StatArray active; // active 块的数量（含 split 出来的）
StatArray inactive_split; // split 出来但未使用的块数

StatArray allocated_bytes; // 用户视角的字节数（= block->size 之和）
StatArray reserved_bytes; // 从设备/驱动 reserve 的字节（pool 总和）
StatArray active_bytes; // 活跃块的字节
StatArray inactive_split_bytes;
StatArray requested_bytes; // 用户请求的原始字节（未对齐前）

int64_t num_alloc_retries = 0; // cudaMalloc 失败触发 cache flush 的次数
int64_t num_ooms = 0;
Stat oversize_allocations;
Stat oversize_segments;
int64_t num_sync_all_streams = 0;
int64_t num_device_alloc = 0;
int64_t num_device_free = 0;
...
};

<pre><code class="line-numbers">其中StatArray是区分了small pool, large pool的数组，每个数组的元素包含current/peak/allocated/freed。统计峰值，以及统计累计值
比较关键的点就是这个num\_alloc\_retries，有的话就说明有性能退化了。
<br>

代码中的for\_each\_selected\_stat\_type就是维护这个统计值的

# Trace

精细化的trace，记录每一次内存相关的操作

```C++
struct TraceEntry {
enum Action {
ALLOC, // 用户 malloc
FREE_REQUESTED, // 用户 free 进来
FREE_COMPLETED, // 真正 coalesce 回池（可能比 FREE_REQUESTED 晚，因 record_stream 等 event）
SEGMENT_ALLOC, // cudaMalloc/cuMemCreate
SEGMENT_FREE, // cudaFree
SEGMENT_MAP, // cuMemMap（expandable）
SEGMENT_UNMAP, // cuMemUnmap（expandable）
SNAPSHOT, // 快照标记（用于和 snapshot 对齐）
OOM // addr_ 字段在这里被借用，存的是 cudaMemGetInfo 报的 free bytes
};
...
Action action_;
c10::DeviceIndex device_;
size_t addr_;
std::shared_ptr<GatheredContext> context_; // 调用栈（Python 栈，可选）
void* stream_{};
size_t size_;
MempoolId_t mempool_;
trace_time_ time_{};
std::string compile_context_; // 当前 torch.compile 阶段名（"FX trace", "Inductor lowering"...）
std::string user_metadata_; // 用户通过 _record_user_metadata 注的字符串
};

• 包括具体的操作，device，stream，分配的地址，大小等信息

• 区分了FREE_REQUESTED/FREE_COMPLETED，用来观察record stream导致的延迟回收

• context可以认为是python的traceback，用来记录分配的栈信息

• time，分配的时间

在DeviceCachingAllocator中维护了一个Ringbuffer。ring buffer的大小通过_record_memory_history(max_entries=...)来决定。

• Ring buffer会维护起点和终点，所以输出的时候trace是按照时间顺序输出的

代码中的record_trace就是生成trace entry，并记录到ring buffer中。同时也会调用若干个callback，对应出现内存操作时候的动作（比如做一些记录）

• AI说这里的CUPTI的内存事件就是从这里抓取的，这块我没有细追

Python层

torch.cuda._record_memory_history，调用到_cuda_record_memory_history
torch.cuda._snapshot/_dump_snapshot，调用到_cuda_memorySnapshot

_cuda_record_memory_history对应到Allocator的recordHistory，这里会把record_history这个开关打开，后续的内存操作就会被记录到上面的ring buffer中。
_cuda_memorySnapshot对应到Allocator的snapshot

• 这里会把ring buffer的trace返回出去

• 以及所有分配的segement的元信息，比如size，block的占用情况等

snapshot本身也会记录一个snapshot的事件，这样方便多次snapshot做diff，做对齐

Profiler

• 核心接口就是reportMemoryUsageToProfiler
  • 会拿一个thread local的debug info，里面会有一个MemoryReportingInfoBase的指针，用这个来做report

  • 记录ptr, alloc_size, device。如果是分配alloc_size就是正数，free就是负数

  • 用户层的语义，不涉及到caching allocator内部的行为（不感知segment之类的信息）

• torch.profiler.profile(profile_memory=True)的时候，这个thread local的debug info就会被塞一个report进去。
  • 没开profiler的时候，指针为空，直接返回

MemoryViz

Memory viz的脚本在torch/cuda/_memory_viz.py中
要求输入的schema：

{
  "segments": [...],          # 物理段列表，每段含 blocks
  "device_traces": [[...]],   # 每个 device 一条 trace 事件流（alloc/free_*/segment_*/...）
  "external_annotations": [...],
}

Record memory history + dump snapshot出来的东西就是这个格式，所以可以直接用。

但是平常使用的torch profiler也可以用memory snapshot，是走的另一条路。
在_profile_to_snapshot会把 profiler 的 tensor 生命周期事件，伪装成 caching allocator 的 trace 格式。profile记录的是每一个tensor的分配情况。相对来说粗粒度一些。

走trace的方法更细粒度一些，可以看到详细的事件，用来debug内存碎片。

运维观测

注意点：

• allocation/active的区别
  • 统计口径都是block，（对齐后的），用户申请的是requested_bytes

  • 调用free时，allocation减。真正变成free时，active减。所以主要是record stream影响这里的行为

count类

SUM 类指标（字节数）

reserved = active + inactive_split + 一些未切分空闲块 *allocated ≤ active ≤ reserved**，三者拉开越大说明缓存/碎片越多。*

全局counter，统计关键事件