函数

clear_traces() 函数

清除 Python 分配的内存块的追踪。

另请参阅 stop()。

get_object_traceback(obj) 函数

获取 Python 对象 obj 分配位置的回溯。返回一个 Traceback 实例，如果 tracemalloc 模块未追踪内存分配或未追踪对象的分配，则返回 None。

另请参阅 gc.get_referrers() 和 sys.getsizeof() 函数。

get_traceback_limit() 函数

获取追踪中存储的回溯中的最大帧数。

tracemalloc 模块必须追踪内存分配才能获取限制，否则会引发异常。

限制由 start() 函数设置。

get_traced_memory() 函数

获取 tracemalloc 模块追踪的内存块的当前大小和最大大小，作为一个元组：(size: int, max_size: int)。

get_tracemalloc_memory() 函数

获取用于存储内存块追踪的 tracemalloc 模块的内存使用情况（以字节为单位）。返回一个 int。

is_tracing() 函数

如果 tracemalloc 模块正在追踪 Python 内存分配，则为 True，否则为 False。

另请参阅 start() 和 stop() 函数。

start(nframe: int=1) 函数

开始追踪 Python 内存分配：在 Python 内存分配器上安装钩子。收集到的追踪的回溯将限制为 nframe 帧。默认情况下，内存块的追踪仅存储最近的帧：限制为 1。nframe 必须大于或等于 1。

存储超过 1 帧仅对计算按 'traceback' 分组的统计信息或计算累积统计信息有用：请参阅 Snapshot.compare_to() 和 Snapshot.statistics() 方法。

存储更多帧会增加 tracemalloc 模块的内存和 CPU 开销。使用 get_tracemalloc_memory() 函数来衡量 tracemalloc 模块使用了多少内存。

PYTHONTRACEMALLOC 环境变量（PYTHONTRACEMALLOC=NFRAME）和 -X tracemalloc=NFRAME 命令行选项可用于在启动时开始追踪。

另请参阅 stop()、is_tracing() 和 get_traceback_limit() 函数。

stop() 函数

停止追踪 Python 内存分配：卸载 Python 内存分配器上的钩子。还清除 Python 分配的内存块的追踪

调用 take_snapshot() 函数以在清除追踪之前获取追踪的快照。

另请参阅 start() 和 is_tracing() 函数。

take_snapshot() 函数

获取 Python 分配的内存块的追踪的快照。返回一个新的 Snapshot 实例。

快照不包括 tracemalloc 模块开始追踪内存分配之前分配的内存块。

追踪的回溯限制为 get_traceback_limit() 帧。使用 start() 函数的 nframe 参数来存储更多帧。

tracemalloc 模块必须追踪内存分配才能获取快照，请参阅 start() 函数。

另请参阅 get_object_traceback() 函数。

过滤器

Filter(inclusive: bool, filename_pattern: str, lineno: int=None, all_frames: bool=False) 类

用于过滤内存块跟踪信息的过滤器。

有关filename_pattern的语法，请参阅fnmatch.fnmatch()函数。文件扩展名'.pyc'和'.pyo'会被替换为'.py'。

示例

• Filter(True, subprocess.__file__) 仅包含subprocess模块的跟踪信息
• Filter(False, tracemalloc.__file__) 排除tracemalloc模块的跟踪信息
• Filter(False, "<unknown>") 排除空回溯信息

inclusive 属性

如果inclusive为True（包含），则仅跟踪在名称与filename_pattern匹配的文件中第lineno行分配的内存块。

如果inclusive为False（排除），则忽略在名称与filename_pattern匹配的文件中第lineno行分配的内存块。

lineno 属性

过滤器的行号（int）。如果lineno为None，则过滤器匹配任何行号。

filename_pattern 属性

过滤器的文件名模式（str）。

all_frames 属性

如果all_frames为True，则检查回溯中的所有帧。如果all_frames为False，则仅检查最近的帧。

如果回溯限制小于2，则忽略此属性。请参阅get_traceback_limit()函数和Snapshot.traceback_limit属性。

帧

Frame 类

回溯中的一个帧。

Traceback类是Frame实例的序列。

filename 属性

文件名（str）。

lineno 属性

行号（int）。

快照

Snapshot 类

Python分配的内存块跟踪信息的快照。

take_snapshot()函数创建一个快照实例。

compare_to(old_snapshot: Snapshot, group_by: str, cumulative: bool=False) 方法

计算与旧快照的差异。根据group_by对结果进行分组，并以排序后的StatisticDiff实例列表的形式返回统计信息。

有关group_by和cumulative参数，请参阅statistics()方法。

结果根据以下顺序排序：StatisticDiff.size_diff的绝对值、StatisticDiff.size、StatisticDiff.count_diff的绝对值、Statistic.count，最后是StatisticDiff.traceback，从大到小排序。

dump(filename) 方法

将快照写入文件。

使用load()重新加载快照。

filter_traces(filters) 方法

创建一个新的Snapshot实例，其中包含经过过滤的traces序列，filters是一个Filter实例列表。如果filters为空列表，则返回一个新的Snapshot实例，其中包含traces的副本。

所有包含过滤器同时应用，如果没有任何包含过滤器匹配则忽略跟踪。如果至少有一个排除过滤器匹配，则忽略跟踪。

load(filename) 类方法

从文件加载快照。

另请参阅dump()。

statistics(group_by: str, cumulative: bool=False) 方法

根据group_by对结果进行分组，并以排序后的Statistic实例列表的形式返回统计信息。

group_by	描述
'filename'	文件名
'lineno'	文件名和行号
'traceback'	回溯

如果cumulative为True，则累加跟踪回溯中所有帧的内存块大小和数量，而不仅仅是最新的帧。累积模式只能与group_by等于'filename'和'lineno'以及traceback_limit大于1一起使用。

结果根据以下顺序排序：Statistic.size、Statistic.count，最后是Statistic.traceback，从大到小排序。

traceback_limit 属性

存储在traces回溯中的最大帧数：在拍摄快照时get_traceback_limit()的结果。

traces 属性

Python分配的所有内存块的跟踪信息：Trace实例的序列。

序列的顺序未定义。使用Snapshot.statistics()方法获取排序后的统计信息列表。

统计信息

Statistic 类

内存分配的统计信息。

Snapshot.statistics()返回一个Statistic实例列表。

另请参阅StatisticDiff类。

count 属性

内存块的数量（int）。

size 属性

内存块的总大小（以字节为单位）（int）。

traceback 属性

分配内存块的回溯，Traceback实例。

统计信息差异

StatisticDiff 类

旧快照和新快照之间内存分配的统计差异。Snapshot 实例。

Snapshot.compare_to()返回一个StatisticDiff实例列表。另请参阅Statistic类。

count 属性

新快照中内存块的数量（int）：如果内存块在新快照中已释放，则为0。

count_diff 属性

旧快照和新快照之间内存块数量的差异（int）：如果内存块在新快照中已分配，则为0。

size 属性

新快照中内存块的总大小（以字节为单位）（int）：如果内存块在新快照中已释放，则为0。

size_diff 属性

旧快照和新快照之间内存块总大小的差异（以字节为单位）（int）：如果内存块在新快照中已分配，则为0。

traceback 属性

分配内存块的回溯，Traceback实例。

追踪

Trace 类

内存块的跟踪信息。

Snapshot.traces属性是Trace实例的序列。

size 属性

内存块的大小（以字节为单位）（int）。

traceback 属性

分配内存块的回溯，Traceback实例。

回溯

Traceback 类

从最近的帧到最旧的帧排序的Frame实例序列。

回溯至少包含1个帧。如果tracemalloc模块无法获取帧，则使用文件名"<unknown>"和行号0。

拍摄快照时，跟踪的回溯将限制为get_traceback_limit()帧。请参阅take_snapshot()函数。

Trace.traceback属性是Traceback实例。

记录对内存分配器的调用

另一种方法是记录对malloc()、realloc()和free()函数的调用。调用可以记录到文件中，或通过网络发送到另一台计算机。日志条目的示例：函数名称、内存块的大小、内存块的地址、发生分配的Python回溯、时间戳。

日志不能直接使用，获取内存的当前状态需要解析之前的日志。例如，无法直接获取Python对象的回溯信息，就像get_object_traceback(obj) 使用跟踪信息那样。

Python 使用生命周期非常短的对象，因此大量使用内存分配器。它有一个针对生命周期短的小对象（小于 512 字节）优化的分配器。例如，Python 测试套件平均每秒调用 malloc()、realloc() 或 free() 270,000 次。如果日志条目的大小为 32 字节，则日志记录每秒产生 8.2 MB 或每小时 29.0 GB。

该方案被否决，因为它效率较低且功能较少。在不同的进程或不同的计算机上解析日志比在同一进程中维护分配的内存块上的跟踪信息要慢。