API

The version of the module is tracemalloc.__version__ (string), example: "1.2".

Functions

clear_traces()

Clear traces of memory blocks allocated by Python.

See also stop().

get_object_traceback(obj)

Get the traceback where the Python object obj was allocated. Return a Traceback instance, or None if the tracemalloc module is not tracing memory allocations or did not trace the allocation of the object.

See also gc.get_referrers() and sys.getsizeof() functions.

get_traceback_limit()

Get the maximum number of frames stored in the traceback of a trace.

The tracemalloc module must be tracing memory allocations to get the limit, otherwise an exception is raised.

The limit is set by the start() function.

get_traced_memory()

Get the current size and peak size of memory blocks traced by the tracemalloc module as a tuple: (current: int, peak: int).

get_tracemalloc_memory()

Get the memory usage in bytes of the tracemalloc module used to store traces of memory blocks. Return an int.

is_tracing()

True if the tracemalloc module is tracing Python memory allocations, False otherwise.

See also start() and stop() functions.

start(nframe: int=1)

Start tracing Python memory allocations: install hooks on Python memory allocators. Collected tracebacks of traces will be limited to nframe frames. By default, a trace of a memory block only stores the most recent frame: the limit is 1. nframe must be greater or equal to 1.

Storing more than 1 frame is only useful to compute statistics grouped by 'traceback' or to compute cumulative statistics: see the Snapshot.compare_to() and Snapshot.statistics() methods.

Storing more frames increases the memory and CPU overhead of the tracemalloc module. Use the get_tracemalloc_memory() function to measure how much memory is used by the tracemalloc module.

See also stop(), is_tracing() and get_traceback_limit() functions.

stop()

Stop tracing Python memory allocations: uninstall hooks on Python memory allocators. Also clears all previously collected traces of memory blocks allocated by Python.

Call take_snapshot() function to take a snapshot of traces before clearing them.

See also start(), is_tracing() and clear_traces() functions.

take_snapshot()

Take a snapshot of traces of memory blocks allocated by Python. Return a new Snapshot instance.

The snapshot does not include memory blocks allocated before the tracemalloc module started to trace memory allocations.

Tracebacks of traces are limited to get_traceback_limit() frames. Use the nframe parameter of the start() function to store more frames.

The tracemalloc module must be tracing memory allocations to take a snapshot, see the the start() function.

See also the get_object_traceback() function.

Filter

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

Filter on traces of memory blocks.

See the fnmatch.fnmatch() function for the syntax of filename_pattern. The '.pyc' and '.pyo' file extensions are replaced with '.py'.

Examples:

  • Filter(True, subprocess.__file__) only includes traces of the subprocess module
  • Filter(False, tracemalloc.__file__) excludes traces of the tracemalloc module
  • Filter(False, "<unknown>") excludes empty tracebacks
inclusive

If inclusive is True (include), only trace memory blocks allocated in a file with a name matching filename_pattern at line number lineno.

If inclusive is False (exclude), ignore memory blocks allocated in a file with a name matching filename_pattern at line number lineno.

lineno

Line number (int) of the filter. If lineno is None, the filter matches any line number.

filename_pattern

Filename pattern of the filter (str).

all_frames

If all_frames is True, all frames of the traceback are checked. If all_frames is False, only the most recent frame is checked.

This attribute has no effect if the traceback limit is 1. See the get_traceback_limit() function and Snapshot.traceback_limit attribute.

Frame

class Frame

Frame of a traceback.

The Traceback class is a sequence of Frame instances.

filename

Filename (str).

lineno

Line number (int).

Snapshot

class Snapshot

Snapshot of traces of memory blocks allocated by Python.

The take_snapshot() function creates a snapshot instance.

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

Compute the differences with an old snapshot. Get statistics as a sorted list of StatisticDiff instances grouped by group_by.

See the statistics() method for group_by and cumulative parameters.

The result is sorted from the biggest to the smallest by: absolute value of StatisticDiff.size_diff, StatisticDiff.size, absolute value of StatisticDiff.count_diff, Statistic.count and then by StatisticDiff.traceback.

dump(filename)

Write the snapshot into a file.

Use load() to reload the snapshot.

filter_traces(filters)

Create a new Snapshot instance with a filtered traces sequence, filters is a list of Filter instances. If filters is an empty list, return a new Snapshot instance with a copy of the traces.

All inclusive filters are applied at once, a trace is ignored if no inclusive filters match it. A trace is ignored if at least one exclusive filter matchs it.

classmethod load(filename)

Load a snapshot from a file.

See also dump().

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

Get statistics as a sorted list of Statistic instances grouped by group_by:

group_by description
'filename' filename
'lineno' filename and line number
'traceback' traceback

If cumulative is True, cumulate size and count of memory blocks of all frames of the traceback of a trace, not only the most recent frame. The cumulative mode can only be used with group_by equals to 'filename' and 'lineno'.

The result is sorted from the biggest to the smallest by: Statistic.size, Statistic.count and then by Statistic.traceback.

traceback_limit

Maximum number of frames stored in the traceback of traces: result of the get_traceback_limit() when the snapshot was taken.

traces

Traces of all memory blocks allocated by Python: sequence of Trace instances.

The sequence has an undefined order. Use the Snapshot.statistics() method to get a sorted list of statistics.

Statistic

class Statistic

Statistic on memory allocations.

Snapshot.statistics() returns a list of Statistic instances.

See also the StatisticDiff class.

count

Number of memory blocks (int).

size

Total size of memory blocks in bytes (int).

traceback

Traceback where the memory block was allocated, Traceback instance.

StatisticDiff

class StatisticDiff

Statistic difference on memory allocations between an old and a new Snapshot instance.

Snapshot.compare_to() returns a list of StatisticDiff instances. See also the Statistic class.

count

Number of memory blocks in the new snapshot (int): 0 if the memory blocks have been released in the new snapshot.

count_diff

Difference of number of memory blocks between the old and the new snapshots (int): 0 if the memory blocks have been allocated in the new snapshot.

size

Total size of memory blocks in bytes in the new snapshot (int): 0 if the memory blocks have been released in the new snapshot.

size_diff

Difference of total size of memory blocks in bytes between the old and the new snapshots (int): 0 if the memory blocks have been allocated in the new snapshot.

traceback

Traceback where the memory blocks were allocated, Traceback instance.

Trace

class Trace

Trace of a memory block.

The Snapshot.traces attribute is a sequence of Trace instances.

size

Size of the memory block in bytes (int).

traceback

Traceback where the memory block was allocated, Traceback instance.

Traceback

class Traceback

Sequence of Frame instances sorted from the most recent frame to the oldest frame.

A traceback contains at least 1 frame. If the tracemalloc module failed to get a frame, the filename "<unknown>" at line number 0 is used.

When a snapshot is taken, tracebacks of traces are limited to get_traceback_limit() frames. See the take_snapshot() function.

The Trace.traceback attribute is an instance of Traceback instance.

Differences between pytracemalloc (PyPI) and tracemalloc (stdlib)

The tracemalloc module is part of the Python standard library since Python 3.4: read tracemalloc module documentation.

There are differences between the third party pytracemalloc module (downloaded from PyPI) and the tracemalloc which is part of the Python standard library:

  • stdlib tracemalloc supports a PYTHONTRACEMALLOC environment variable to start tracing at Python startup.
  • stdlib tracemalloc supports a -X tracemalloc=NFRAMES command line option to start tracing at Python startup.