函数

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 实例。

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

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 实例之间内存分配的统计差异。

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。

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