| 1 |
:mod:`!tracemalloc` --- Trace memory allocations |
| 2 |
================================================ |
| 3 |
|
| 4 |
.. module:: tracemalloc |
| 5 |
:synopsis: Trace memory allocations. |
| 6 |
|
| 7 |
.. versionadded:: 3.4 |
| 8 |
|
| 9 |
**Source code:** :source:`Lib/tracemalloc.py` |
| 10 |
|
| 11 |
-------------- |
| 12 |
|
| 13 |
The tracemalloc module is a debug tool to trace memory blocks allocated by |
| 14 |
Python. It provides the following information: |
| 15 |
|
| 16 |
* Traceback where an object was allocated |
| 17 |
* Statistics on allocated memory blocks per filename and per line number: |
| 18 |
total size, number and average size of allocated memory blocks |
| 19 |
* Compute the differences between two snapshots to detect memory leaks |
| 20 |
|
| 21 |
To trace most memory blocks allocated by Python, the module should be started |
| 22 |
as early as possible by setting the :envvar:`PYTHONTRACEMALLOC` environment |
| 23 |
variable to ``1``, or by using :option:`-X` ``tracemalloc`` command line |
| 24 |
option. The :func:`tracemalloc.start` function can be called at runtime to |
| 25 |
start tracing Python memory allocations. |
| 26 |
|
| 27 |
By default, a trace of an allocated memory block only stores the most recent |
| 28 |
frame (1 frame). To store 25 frames at startup: set the |
| 29 |
:envvar:`PYTHONTRACEMALLOC` environment variable to ``25``, or use the |
| 30 |
:option:`-X` ``tracemalloc=25`` command line option. |
| 31 |
|
| 32 |
|
| 33 |
Examples |
| 34 |
-------- |
| 35 |
|
| 36 |
Display the top 10 |
| 37 |
^^^^^^^^^^^^^^^^^^ |
| 38 |
|
| 39 |
Display the 10 files allocating the most memory:: |
| 40 |
|
| 41 |
import tracemalloc |
| 42 |
|
| 43 |
tracemalloc.start() |
| 44 |
|
| 45 |
# ... run your application ... |
| 46 |
|
| 47 |
snapshot = tracemalloc.take_snapshot() |
| 48 |
top_stats = snapshot.statistics('lineno') |
| 49 |
|
| 50 |
print("[ Top 10 ]") |
| 51 |
for stat in top_stats[:10]: |
| 52 |
print(stat) |
| 53 |
|
| 54 |
|
| 55 |
Example of output of the Python test suite:: |
| 56 |
|
| 57 |
[ Top 10 ] |
| 58 |
<frozen importlib._bootstrap>:716: size=4855 KiB, count=39328, average=126 B |
| 59 |
<frozen importlib._bootstrap>:284: size=521 KiB, count=3199, average=167 B |
| 60 |
/usr/lib/python3.4/collections/__init__.py:368: size=244 KiB, count=2315, average=108 B |
| 61 |
/usr/lib/python3.4/unittest/case.py:381: size=185 KiB, count=779, average=243 B |
| 62 |
/usr/lib/python3.4/unittest/case.py:402: size=154 KiB, count=378, average=416 B |
| 63 |
/usr/lib/python3.4/abc.py:133: size=88.7 KiB, count=347, average=262 B |
| 64 |
<frozen importlib._bootstrap>:1446: size=70.4 KiB, count=911, average=79 B |
| 65 |
<frozen importlib._bootstrap>:1454: size=52.0 KiB, count=25, average=2131 B |
| 66 |
<string>:5: size=49.7 KiB, count=148, average=344 B |
| 67 |
/usr/lib/python3.4/sysconfig.py:411: size=48.0 KiB, count=1, average=48.0 KiB |
| 68 |
|
| 69 |
We can see that Python loaded ``4855 KiB`` data (bytecode and constants) from |
| 70 |
modules and that the :mod:`collections` module allocated ``244 KiB`` to build |
| 71 |
:class:`~collections.namedtuple` types. |
| 72 |
|
| 73 |
See :meth:`Snapshot.statistics` for more options. |
| 74 |
|
| 75 |
|
| 76 |
Compute differences |
| 77 |
^^^^^^^^^^^^^^^^^^^ |
| 78 |
|
| 79 |
Take two snapshots and display the differences:: |
| 80 |
|
| 81 |
import tracemalloc |
| 82 |
tracemalloc.start() |
| 83 |
# ... start your application ... |
| 84 |
|
| 85 |
snapshot1 = tracemalloc.take_snapshot() |
| 86 |
# ... call the function leaking memory ... |
| 87 |
snapshot2 = tracemalloc.take_snapshot() |
| 88 |
|
| 89 |
top_stats = snapshot2.compare_to(snapshot1, 'lineno') |
| 90 |
|
| 91 |
print("[ Top 10 differences ]") |
| 92 |
for stat in top_stats[:10]: |
| 93 |
print(stat) |
| 94 |
|
| 95 |
Example of output before/after running some tests of the Python test suite:: |
| 96 |
|
| 97 |
[ Top 10 differences ] |
| 98 |
<frozen importlib._bootstrap>:716: size=8173 KiB (+4428 KiB), count=71332 (+39369), average=117 B |
| 99 |
/usr/lib/python3.4/linecache.py:127: size=940 KiB (+940 KiB), count=8106 (+8106), average=119 B |
| 100 |
/usr/lib/python3.4/unittest/case.py:571: size=298 KiB (+298 KiB), count=589 (+589), average=519 B |
| 101 |
<frozen importlib._bootstrap>:284: size=1005 KiB (+166 KiB), count=7423 (+1526), average=139 B |
| 102 |
/usr/lib/python3.4/mimetypes.py:217: size=112 KiB (+112 KiB), count=1334 (+1334), average=86 B |
| 103 |
/usr/lib/python3.4/http/server.py:848: size=96.0 KiB (+96.0 KiB), count=1 (+1), average=96.0 KiB |
| 104 |
/usr/lib/python3.4/inspect.py:1465: size=83.5 KiB (+83.5 KiB), count=109 (+109), average=784 B |
| 105 |
/usr/lib/python3.4/unittest/mock.py:491: size=77.7 KiB (+77.7 KiB), count=143 (+143), average=557 B |
| 106 |
/usr/lib/python3.4/urllib/parse.py:476: size=71.8 KiB (+71.8 KiB), count=969 (+969), average=76 B |
| 107 |
/usr/lib/python3.4/contextlib.py:38: size=67.2 KiB (+67.2 KiB), count=126 (+126), average=546 B |
| 108 |
|
| 109 |
We can see that Python has loaded ``8173 KiB`` of module data (bytecode and |
| 110 |
constants), and that this is ``4428 KiB`` more than had been loaded before the |
| 111 |
tests, when the previous snapshot was taken. Similarly, the :mod:`linecache` |
| 112 |
module has cached ``940 KiB`` of Python source code to format tracebacks, all |
| 113 |
of it since the previous snapshot. |
| 114 |
|
| 115 |
If the system has little free memory, snapshots can be written on disk using |
| 116 |
the :meth:`Snapshot.dump` method to analyze the snapshot offline. Then use the |
| 117 |
:meth:`Snapshot.load` method reload the snapshot. |
| 118 |
|
| 119 |
|
| 120 |
Get the traceback of a memory block |
| 121 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 122 |
|
| 123 |
Code to display the traceback of the biggest memory block:: |
| 124 |
|
| 125 |
import tracemalloc |
| 126 |
|
| 127 |
# Store 25 frames |
| 128 |
tracemalloc.start(25) |
| 129 |
|
| 130 |
# ... run your application ... |
| 131 |
|
| 132 |
snapshot = tracemalloc.take_snapshot() |
| 133 |
top_stats = snapshot.statistics('traceback') |
| 134 |
|
| 135 |
# pick the biggest memory block |
| 136 |
stat = top_stats[0] |
| 137 |
print("%s memory blocks: %.1f KiB" % (stat.count, stat.size / 1024)) |
| 138 |
for line in stat.traceback.format(): |
| 139 |
print(line) |
| 140 |
|
| 141 |
Example of output of the Python test suite (traceback limited to 25 frames):: |
| 142 |
|
| 143 |
903 memory blocks: 870.1 KiB |
| 144 |
File "<frozen importlib._bootstrap>", line 716 |
| 145 |
File "<frozen importlib._bootstrap>", line 1036 |
| 146 |
File "<frozen importlib._bootstrap>", line 934 |
| 147 |
File "<frozen importlib._bootstrap>", line 1068 |
| 148 |
File "<frozen importlib._bootstrap>", line 619 |
| 149 |
File "<frozen importlib._bootstrap>", line 1581 |
| 150 |
File "<frozen importlib._bootstrap>", line 1614 |
| 151 |
File "/usr/lib/python3.4/doctest.py", line 101 |
| 152 |
import pdb |
| 153 |
File "<frozen importlib._bootstrap>", line 284 |
| 154 |
File "<frozen importlib._bootstrap>", line 938 |
| 155 |
File "<frozen importlib._bootstrap>", line 1068 |
| 156 |
File "<frozen importlib._bootstrap>", line 619 |
| 157 |
File "<frozen importlib._bootstrap>", line 1581 |
| 158 |
File "<frozen importlib._bootstrap>", line 1614 |
| 159 |
File "/usr/lib/python3.4/test/support/__init__.py", line 1728 |
| 160 |
import doctest |
| 161 |
File "/usr/lib/python3.4/test/test_pickletools.py", line 21 |
| 162 |
support.run_doctest(pickletools) |
| 163 |
File "/usr/lib/python3.4/test/regrtest.py", line 1276 |
| 164 |
test_runner() |
| 165 |
File "/usr/lib/python3.4/test/regrtest.py", line 976 |
| 166 |
display_failure=not verbose) |
| 167 |
File "/usr/lib/python3.4/test/regrtest.py", line 761 |
| 168 |
match_tests=ns.match_tests) |
| 169 |
File "/usr/lib/python3.4/test/regrtest.py", line 1563 |
| 170 |
main() |
| 171 |
File "/usr/lib/python3.4/test/__main__.py", line 3 |
| 172 |
regrtest.main_in_temp_cwd() |
| 173 |
File "/usr/lib/python3.4/runpy.py", line 73 |
| 174 |
exec(code, run_globals) |
| 175 |
File "/usr/lib/python3.4/runpy.py", line 160 |
| 176 |
"__main__", fname, loader, pkg_name) |
| 177 |
|
| 178 |
We can see that the most memory was allocated in the :mod:`importlib` module to |
| 179 |
load data (bytecode and constants) from modules: ``870.1 KiB``. The traceback is |
| 180 |
where the :mod:`importlib` loaded data most recently: on the ``import pdb`` |
| 181 |
line of the :mod:`doctest` module. The traceback may change if a new module is |
| 182 |
loaded. |
| 183 |
|
| 184 |
|
| 185 |
Pretty top |
| 186 |
^^^^^^^^^^ |
| 187 |
|
| 188 |
Code to display the 10 lines allocating the most memory with a pretty output, |
| 189 |
ignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files:: |
| 190 |
|
| 191 |
import linecache |
| 192 |
import os |
| 193 |
import tracemalloc |
| 194 |
|
| 195 |
def display_top(snapshot, key_type='lineno', limit=10): |
| 196 |
snapshot = snapshot.filter_traces(( |
| 197 |
tracemalloc.Filter(False, "<frozen importlib._bootstrap>"), |
| 198 |
tracemalloc.Filter(False, "<unknown>"), |
| 199 |
)) |
| 200 |
top_stats = snapshot.statistics(key_type) |
| 201 |
|
| 202 |
print("Top %s lines" % limit) |
| 203 |
for index, stat in enumerate(top_stats[:limit], 1): |
| 204 |
frame = stat.traceback[0] |
| 205 |
print("#%s: %s:%s: %.1f KiB" |
| 206 |
% (index, frame.filename, frame.lineno, stat.size / 1024)) |
| 207 |
line = linecache.getline(frame.filename, frame.lineno).strip() |
| 208 |
if line: |
| 209 |
print(' %s' % line) |
| 210 |
|
| 211 |
other = top_stats[limit:] |
| 212 |
if other: |
| 213 |
size = sum(stat.size for stat in other) |
| 214 |
print("%s other: %.1f KiB" % (len(other), size / 1024)) |
| 215 |
total = sum(stat.size for stat in top_stats) |
| 216 |
print("Total allocated size: %.1f KiB" % (total / 1024)) |
| 217 |
|
| 218 |
tracemalloc.start() |
| 219 |
|
| 220 |
# ... run your application ... |
| 221 |
|
| 222 |
snapshot = tracemalloc.take_snapshot() |
| 223 |
display_top(snapshot) |
| 224 |
|
| 225 |
Example of output of the Python test suite:: |
| 226 |
|
| 227 |
Top 10 lines |
| 228 |
#1: Lib/base64.py:414: 419.8 KiB |
| 229 |
_b85chars2 = [(a + b) for a in _b85chars for b in _b85chars] |
| 230 |
#2: Lib/base64.py:306: 419.8 KiB |
| 231 |
_a85chars2 = [(a + b) for a in _a85chars for b in _a85chars] |
| 232 |
#3: collections/__init__.py:368: 293.6 KiB |
| 233 |
exec(class_definition, namespace) |
| 234 |
#4: Lib/abc.py:133: 115.2 KiB |
| 235 |
cls = super().__new__(mcls, name, bases, namespace) |
| 236 |
#5: unittest/case.py:574: 103.1 KiB |
| 237 |
testMethod() |
| 238 |
#6: Lib/linecache.py:127: 95.4 KiB |
| 239 |
lines = fp.readlines() |
| 240 |
#7: urllib/parse.py:476: 71.8 KiB |
| 241 |
for a in _hexdig for b in _hexdig} |
| 242 |
#8: <string>:5: 62.0 KiB |
| 243 |
#9: Lib/_weakrefset.py:37: 60.0 KiB |
| 244 |
self.data = set() |
| 245 |
#10: Lib/base64.py:142: 59.8 KiB |
| 246 |
_b32tab2 = [a + b for a in _b32tab for b in _b32tab] |
| 247 |
6220 other: 3602.8 KiB |
| 248 |
Total allocated size: 5303.1 KiB |
| 249 |
|
| 250 |
See :meth:`Snapshot.statistics` for more options. |
| 251 |
|
| 252 |
Record the current and peak size of all traced memory blocks |
| 253 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 254 |
|
| 255 |
The following code computes two sums like ``0 + 1 + 2 + ...`` inefficiently, by |
| 256 |
creating a list of those numbers. This list consumes a lot of memory |
| 257 |
temporarily. We can use :func:`get_traced_memory` and :func:`reset_peak` to |
| 258 |
observe the small memory usage after the sum is computed as well as the peak |
| 259 |
memory usage during the computations:: |
| 260 |
|
| 261 |
import tracemalloc |
| 262 |
|
| 263 |
tracemalloc.start() |
| 264 |
|
| 265 |
# Example code: compute a sum with a large temporary list |
| 266 |
large_sum = sum(list(range(100000))) |
| 267 |
|
| 268 |
first_size, first_peak = tracemalloc.get_traced_memory() |
| 269 |
|
| 270 |
tracemalloc.reset_peak() |
| 271 |
|
| 272 |
# Example code: compute a sum with a small temporary list |
| 273 |
small_sum = sum(list(range(1000))) |
| 274 |
|
| 275 |
second_size, second_peak = tracemalloc.get_traced_memory() |
| 276 |
|
| 277 |
print(f"{first_size=}, {first_peak=}") |
| 278 |
print(f"{second_size=}, {second_peak=}") |
| 279 |
|
| 280 |
Output:: |
| 281 |
|
| 282 |
first_size=664, first_peak=3592984 |
| 283 |
second_size=804, second_peak=29704 |
| 284 |
|
| 285 |
Using :func:`reset_peak` ensured we could accurately record the peak during the |
| 286 |
computation of ``small_sum``, even though it is much smaller than the overall |
| 287 |
peak size of memory blocks since the :func:`start` call. Without the call to |
| 288 |
:func:`reset_peak`, ``second_peak`` would still be the peak from the |
| 289 |
computation ``large_sum`` (that is, equal to ``first_peak``). In this case, |
| 290 |
both peaks are much higher than the final memory usage, and which suggests we |
| 291 |
could optimise (by removing the unnecessary call to :class:`list`, and writing |
| 292 |
``sum(range(...))``). |
| 293 |
|
| 294 |
API |
| 295 |
--- |
| 296 |
|
| 297 |
Functions |
| 298 |
^^^^^^^^^ |
| 299 |
|
| 300 |
.. function:: clear_traces() |
| 301 |
|
| 302 |
Clear traces of memory blocks allocated by Python. |
| 303 |
|
| 304 |
See also :func:`stop`. |
| 305 |
|
| 306 |
|
| 307 |
.. function:: get_object_traceback(obj) |
| 308 |
|
| 309 |
Get the traceback where the Python object *obj* was allocated. |
| 310 |
Return a :class:`Traceback` instance, or ``None`` if the :mod:`!tracemalloc` |
| 311 |
module is not tracing memory allocations or did not trace the allocation of |
| 312 |
the object. |
| 313 |
|
| 314 |
See also :func:`gc.get_referrers` and :func:`sys.getsizeof` functions. |
| 315 |
|
| 316 |
|
| 317 |
.. function:: get_traceback_limit() |
| 318 |
|
| 319 |
Get the maximum number of frames stored in the traceback of a trace. |
| 320 |
|
| 321 |
The :mod:`!tracemalloc` module must be tracing memory allocations to |
| 322 |
get the limit, otherwise an exception is raised. |
| 323 |
|
| 324 |
The limit is set by the :func:`start` function. |
| 325 |
|
| 326 |
|
| 327 |
.. function:: get_traced_memory() |
| 328 |
|
| 329 |
Get the current size and peak size of memory blocks traced by the |
| 330 |
:mod:`!tracemalloc` module as a tuple: ``(current: int, peak: int)``. |
| 331 |
|
| 332 |
|
| 333 |
.. function:: reset_peak() |
| 334 |
|
| 335 |
Set the peak size of memory blocks traced by the :mod:`!tracemalloc` module |
| 336 |
to the current size. |
| 337 |
|
| 338 |
Do nothing if the :mod:`!tracemalloc` module is not tracing memory |
| 339 |
allocations. |
| 340 |
|
| 341 |
This function only modifies the recorded peak size, and does not modify or |
| 342 |
clear any traces, unlike :func:`clear_traces`. Snapshots taken with |
| 343 |
:func:`take_snapshot` before a call to :func:`reset_peak` can be |
| 344 |
meaningfully compared to snapshots taken after the call. |
| 345 |
|
| 346 |
See also :func:`get_traced_memory`. |
| 347 |
|
| 348 |
.. versionadded:: 3.9 |
| 349 |
|
| 350 |
|
| 351 |
.. function:: get_tracemalloc_memory() |
| 352 |
|
| 353 |
Get the memory usage in bytes of the :mod:`!tracemalloc` module used to store |
| 354 |
traces of memory blocks. |
| 355 |
Return an :class:`int`. |
| 356 |
|
| 357 |
|
| 358 |
.. function:: is_tracing() |
| 359 |
|
| 360 |
``True`` if the :mod:`!tracemalloc` module is tracing Python memory |
| 361 |
allocations, ``False`` otherwise. |
| 362 |
|
| 363 |
See also :func:`start` and :func:`stop` functions. |
| 364 |
|
| 365 |
|
| 366 |
.. function:: start(nframe: int=1) |
| 367 |
|
| 368 |
Start tracing Python memory allocations: install hooks on Python memory |
| 369 |
allocators. Collected tracebacks of traces will be limited to *nframe* |
| 370 |
frames. By default, a trace of a memory block only stores the most recent |
| 371 |
frame: the limit is ``1``. *nframe* must be greater or equal to ``1``. |
| 372 |
|
| 373 |
You can still read the original number of total frames that composed the |
| 374 |
traceback by looking at the :attr:`Traceback.total_nframe` attribute. |
| 375 |
|
| 376 |
Storing more than ``1`` frame is only useful to compute statistics grouped |
| 377 |
by ``'traceback'`` or to compute cumulative statistics: see the |
| 378 |
:meth:`Snapshot.compare_to` and :meth:`Snapshot.statistics` methods. |
| 379 |
|
| 380 |
Storing more frames increases the memory and CPU overhead of the |
| 381 |
:mod:`!tracemalloc` module. Use the :func:`get_tracemalloc_memory` function |
| 382 |
to measure how much memory is used by the :mod:`!tracemalloc` module. |
| 383 |
|
| 384 |
The :envvar:`PYTHONTRACEMALLOC` environment variable |
| 385 |
(``PYTHONTRACEMALLOC=NFRAME``) and the :option:`-X` ``tracemalloc=NFRAME`` |
| 386 |
command line option can be used to start tracing at startup. |
| 387 |
|
| 388 |
See also :func:`stop`, :func:`is_tracing` and :func:`get_traceback_limit` |
| 389 |
functions. |
| 390 |
|
| 391 |
|
| 392 |
.. function:: stop() |
| 393 |
|
| 394 |
Stop tracing Python memory allocations: uninstall hooks on Python memory |
| 395 |
allocators. Also clears all previously collected traces of memory blocks |
| 396 |
allocated by Python. |
| 397 |
|
| 398 |
Call :func:`take_snapshot` function to take a snapshot of traces before |
| 399 |
clearing them. |
| 400 |
|
| 401 |
See also :func:`start`, :func:`is_tracing` and :func:`clear_traces` |
| 402 |
functions. |
| 403 |
|
| 404 |
|
| 405 |
.. function:: take_snapshot() |
| 406 |
|
| 407 |
Take a snapshot of traces of memory blocks allocated by Python. Return a new |
| 408 |
:class:`Snapshot` instance. |
| 409 |
|
| 410 |
The snapshot does not include memory blocks allocated before the |
| 411 |
:mod:`!tracemalloc` module started to trace memory allocations. |
| 412 |
|
| 413 |
Tracebacks of traces are limited to :func:`get_traceback_limit` frames. Use |
| 414 |
the *nframe* parameter of the :func:`start` function to store more frames. |
| 415 |
|
| 416 |
The :mod:`!tracemalloc` module must be tracing memory allocations to take a |
| 417 |
snapshot, see the :func:`start` function. |
| 418 |
|
| 419 |
See also the :func:`get_object_traceback` function. |
| 420 |
|
| 421 |
|
| 422 |
DomainFilter |
| 423 |
^^^^^^^^^^^^ |
| 424 |
|
| 425 |
.. class:: DomainFilter(inclusive: bool, domain: int) |
| 426 |
|
| 427 |
Filter traces of memory blocks by their address space (domain). |
| 428 |
|
| 429 |
.. versionadded:: 3.6 |
| 430 |
|
| 431 |
.. attribute:: inclusive |
| 432 |
|
| 433 |
If *inclusive* is ``True`` (include), match memory blocks allocated |
| 434 |
in the address space :attr:`domain`. |
| 435 |
|
| 436 |
If *inclusive* is ``False`` (exclude), match memory blocks not allocated |
| 437 |
in the address space :attr:`domain`. |
| 438 |
|
| 439 |
.. attribute:: domain |
| 440 |
|
| 441 |
Address space of a memory block (``int``). Read-only property. |
| 442 |
|
| 443 |
|
| 444 |
Filter |
| 445 |
^^^^^^ |
| 446 |
|
| 447 |
.. class:: Filter(inclusive: bool, filename_pattern: str, lineno: int=None, all_frames: bool=False, domain: int=None) |
| 448 |
|
| 449 |
Filter on traces of memory blocks. |
| 450 |
|
| 451 |
See the :func:`fnmatch.fnmatch` function for the syntax of |
| 452 |
*filename_pattern*. The ``'.pyc'`` file extension is |
| 453 |
replaced with ``'.py'``. |
| 454 |
|
| 455 |
Examples: |
| 456 |
|
| 457 |
* ``Filter(True, subprocess.__file__)`` only includes traces of the |
| 458 |
:mod:`subprocess` module |
| 459 |
* ``Filter(False, tracemalloc.__file__)`` excludes traces of the |
| 460 |
:mod:`!tracemalloc` module |
| 461 |
* ``Filter(False, "<unknown>")`` excludes empty tracebacks |
| 462 |
|
| 463 |
|
| 464 |
.. versionchanged:: 3.5 |
| 465 |
The ``'.pyo'`` file extension is no longer replaced with ``'.py'``. |
| 466 |
|
| 467 |
.. versionchanged:: 3.6 |
| 468 |
Added the :attr:`domain` attribute. |
| 469 |
|
| 470 |
|
| 471 |
.. attribute:: domain |
| 472 |
|
| 473 |
Address space of a memory block (``int`` or ``None``). |
| 474 |
|
| 475 |
tracemalloc uses the domain ``0`` to trace memory allocations made by |
| 476 |
Python. C extensions can use other domains to trace other resources. |
| 477 |
|
| 478 |
.. attribute:: inclusive |
| 479 |
|
| 480 |
If *inclusive* is ``True`` (include), only match memory blocks allocated |
| 481 |
in a file with a name matching :attr:`filename_pattern` at line number |
| 482 |
:attr:`lineno`. |
| 483 |
|
| 484 |
If *inclusive* is ``False`` (exclude), ignore memory blocks allocated in |
| 485 |
a file with a name matching :attr:`filename_pattern` at line number |
| 486 |
:attr:`lineno`. |
| 487 |
|
| 488 |
.. attribute:: lineno |
| 489 |
|
| 490 |
Line number (``int``) of the filter. If *lineno* is ``None``, the filter |
| 491 |
matches any line number. |
| 492 |
|
| 493 |
.. attribute:: filename_pattern |
| 494 |
|
| 495 |
Filename pattern of the filter (``str``). Read-only property. |
| 496 |
|
| 497 |
.. attribute:: all_frames |
| 498 |
|
| 499 |
If *all_frames* is ``True``, all frames of the traceback are checked. If |
| 500 |
*all_frames* is ``False``, only the most recent frame is checked. |
| 501 |
|
| 502 |
This attribute has no effect if the traceback limit is ``1``. See the |
| 503 |
:func:`get_traceback_limit` function and :attr:`Snapshot.traceback_limit` |
| 504 |
attribute. |
| 505 |
|
| 506 |
|
| 507 |
Frame |
| 508 |
^^^^^ |
| 509 |
|
| 510 |
.. class:: Frame |
| 511 |
|
| 512 |
Frame of a traceback. |
| 513 |
|
| 514 |
The :class:`Traceback` class is a sequence of :class:`Frame` instances. |
| 515 |
|
| 516 |
.. attribute:: filename |
| 517 |
|
| 518 |
Filename (``str``). |
| 519 |
|
| 520 |
.. attribute:: lineno |
| 521 |
|
| 522 |
Line number (``int``). |
| 523 |
|
| 524 |
|
| 525 |
Snapshot |
| 526 |
^^^^^^^^ |
| 527 |
|
| 528 |
.. class:: Snapshot |
| 529 |
|
| 530 |
Snapshot of traces of memory blocks allocated by Python. |
| 531 |
|
| 532 |
The :func:`take_snapshot` function creates a snapshot instance. |
| 533 |
|
| 534 |
.. method:: compare_to(old_snapshot: Snapshot, key_type: str, cumulative: bool=False) |
| 535 |
|
| 536 |
Compute the differences with an old snapshot. Get statistics as a sorted |
| 537 |
list of :class:`StatisticDiff` instances grouped by *key_type*. |
| 538 |
|
| 539 |
See the :meth:`Snapshot.statistics` method for *key_type* and *cumulative* |
| 540 |
parameters. |
| 541 |
|
| 542 |
The result is sorted from the biggest to the smallest by: absolute value |
| 543 |
of :attr:`StatisticDiff.size_diff`, :attr:`StatisticDiff.size`, absolute |
| 544 |
value of :attr:`StatisticDiff.count_diff`, :attr:`Statistic.count` and |
| 545 |
then by :attr:`StatisticDiff.traceback`. |
| 546 |
|
| 547 |
|
| 548 |
.. method:: dump(filename) |
| 549 |
|
| 550 |
Write the snapshot into a file. |
| 551 |
|
| 552 |
Use :meth:`load` to reload the snapshot. |
| 553 |
|
| 554 |
|
| 555 |
.. method:: filter_traces(filters) |
| 556 |
|
| 557 |
Create a new :class:`Snapshot` instance with a filtered :attr:`traces` |
| 558 |
sequence, *filters* is a list of :class:`DomainFilter` and |
| 559 |
:class:`Filter` instances. If *filters* is an empty list, return a new |
| 560 |
:class:`Snapshot` instance with a copy of the traces. |
| 561 |
|
| 562 |
All inclusive filters are applied at once, a trace is ignored if no |
| 563 |
inclusive filters match it. A trace is ignored if at least one exclusive |
| 564 |
filter matches it. |
| 565 |
|
| 566 |
.. versionchanged:: 3.6 |
| 567 |
:class:`DomainFilter` instances are now also accepted in *filters*. |
| 568 |
|
| 569 |
|
| 570 |
.. classmethod:: load(filename) |
| 571 |
|
| 572 |
Load a snapshot from a file. |
| 573 |
|
| 574 |
See also :meth:`dump`. |
| 575 |
|
| 576 |
|
| 577 |
.. method:: statistics(key_type: str, cumulative: bool=False) |
| 578 |
|
| 579 |
Get statistics as a sorted list of :class:`Statistic` instances grouped |
| 580 |
by *key_type*: |
| 581 |
|
| 582 |
===================== ======================== |
| 583 |
key_type description |
| 584 |
===================== ======================== |
| 585 |
``'filename'`` filename |
| 586 |
``'lineno'`` filename and line number |
| 587 |
``'traceback'`` traceback |
| 588 |
===================== ======================== |
| 589 |
|
| 590 |
If *cumulative* is ``True``, cumulate size and count of memory blocks of |
| 591 |
all frames of the traceback of a trace, not only the most recent frame. |
| 592 |
The cumulative mode can only be used with *key_type* equal to |
| 593 |
``'filename'`` and ``'lineno'``. |
| 594 |
|
| 595 |
The result is sorted from the biggest to the smallest by: |
| 596 |
:attr:`Statistic.size`, :attr:`Statistic.count` and then by |
| 597 |
:attr:`Statistic.traceback`. |
| 598 |
|
| 599 |
|
| 600 |
.. attribute:: traceback_limit |
| 601 |
|
| 602 |
Maximum number of frames stored in the traceback of :attr:`traces`: |
| 603 |
result of the :func:`get_traceback_limit` when the snapshot was taken. |
| 604 |
|
| 605 |
.. attribute:: traces |
| 606 |
|
| 607 |
Traces of all memory blocks allocated by Python: sequence of |
| 608 |
:class:`Trace` instances. |
| 609 |
|
| 610 |
The sequence has an undefined order. Use the :meth:`Snapshot.statistics` |
| 611 |
method to get a sorted list of statistics. |
| 612 |
|
| 613 |
|
| 614 |
Statistic |
| 615 |
^^^^^^^^^ |
| 616 |
|
| 617 |
.. class:: Statistic |
| 618 |
|
| 619 |
Statistic on memory allocations. |
| 620 |
|
| 621 |
:func:`Snapshot.statistics` returns a list of :class:`Statistic` instances. |
| 622 |
|
| 623 |
See also the :class:`StatisticDiff` class. |
| 624 |
|
| 625 |
.. attribute:: count |
| 626 |
|
| 627 |
Number of memory blocks (``int``). |
| 628 |
|
| 629 |
.. attribute:: size |
| 630 |
|
| 631 |
Total size of memory blocks in bytes (``int``). |
| 632 |
|
| 633 |
.. attribute:: traceback |
| 634 |
|
| 635 |
Traceback where the memory block was allocated, :class:`Traceback` |
| 636 |
instance. |
| 637 |
|
| 638 |
|
| 639 |
StatisticDiff |
| 640 |
^^^^^^^^^^^^^ |
| 641 |
|
| 642 |
.. class:: StatisticDiff |
| 643 |
|
| 644 |
Statistic difference on memory allocations between an old and a new |
| 645 |
:class:`Snapshot` instance. |
| 646 |
|
| 647 |
:func:`Snapshot.compare_to` returns a list of :class:`StatisticDiff` |
| 648 |
instances. See also the :class:`Statistic` class. |
| 649 |
|
| 650 |
.. attribute:: count |
| 651 |
|
| 652 |
Number of memory blocks in the new snapshot (``int``): ``0`` if |
| 653 |
the memory blocks have been released in the new snapshot. |
| 654 |
|
| 655 |
.. attribute:: count_diff |
| 656 |
|
| 657 |
Difference of number of memory blocks between the old and the new |
| 658 |
snapshots (``int``): ``0`` if the memory blocks have been allocated in |
| 659 |
the new snapshot. |
| 660 |
|
| 661 |
.. attribute:: size |
| 662 |
|
| 663 |
Total size of memory blocks in bytes in the new snapshot (``int``): |
| 664 |
``0`` if the memory blocks have been released in the new snapshot. |
| 665 |
|
| 666 |
.. attribute:: size_diff |
| 667 |
|
| 668 |
Difference of total size of memory blocks in bytes between the old and |
| 669 |
the new snapshots (``int``): ``0`` if the memory blocks have been |
| 670 |
allocated in the new snapshot. |
| 671 |
|
| 672 |
.. attribute:: traceback |
| 673 |
|
| 674 |
Traceback where the memory blocks were allocated, :class:`Traceback` |
| 675 |
instance. |
| 676 |
|
| 677 |
|
| 678 |
Trace |
| 679 |
^^^^^ |
| 680 |
|
| 681 |
.. class:: Trace |
| 682 |
|
| 683 |
Trace of a memory block. |
| 684 |
|
| 685 |
The :attr:`Snapshot.traces` attribute is a sequence of :class:`Trace` |
| 686 |
instances. |
| 687 |
|
| 688 |
.. versionchanged:: 3.6 |
| 689 |
Added the :attr:`domain` attribute. |
| 690 |
|
| 691 |
.. attribute:: domain |
| 692 |
|
| 693 |
Address space of a memory block (``int``). Read-only property. |
| 694 |
|
| 695 |
tracemalloc uses the domain ``0`` to trace memory allocations made by |
| 696 |
Python. C extensions can use other domains to trace other resources. |
| 697 |
|
| 698 |
.. attribute:: size |
| 699 |
|
| 700 |
Size of the memory block in bytes (``int``). |
| 701 |
|
| 702 |
.. attribute:: traceback |
| 703 |
|
| 704 |
Traceback where the memory block was allocated, :class:`Traceback` |
| 705 |
instance. |
| 706 |
|
| 707 |
|
| 708 |
Traceback |
| 709 |
^^^^^^^^^ |
| 710 |
|
| 711 |
.. class:: Traceback |
| 712 |
|
| 713 |
Sequence of :class:`Frame` instances sorted from the oldest frame to the |
| 714 |
most recent frame. |
| 715 |
|
| 716 |
A traceback contains at least ``1`` frame. If the ``tracemalloc`` module |
| 717 |
failed to get a frame, the filename ``"<unknown>"`` at line number ``0`` is |
| 718 |
used. |
| 719 |
|
| 720 |
When a snapshot is taken, tracebacks of traces are limited to |
| 721 |
:func:`get_traceback_limit` frames. See the :func:`take_snapshot` function. |
| 722 |
The original number of frames of the traceback is stored in the |
| 723 |
:attr:`Traceback.total_nframe` attribute. That allows one to know if a traceback |
| 724 |
has been truncated by the traceback limit. |
| 725 |
|
| 726 |
The :attr:`Trace.traceback` attribute is a :class:`Traceback` instance. |
| 727 |
|
| 728 |
.. versionchanged:: 3.7 |
| 729 |
Frames are now sorted from the oldest to the most recent, instead of most recent to oldest. |
| 730 |
|
| 731 |
.. attribute:: total_nframe |
| 732 |
|
| 733 |
Total number of frames that composed the traceback before truncation. |
| 734 |
This attribute can be set to ``None`` if the information is not |
| 735 |
available. |
| 736 |
|
| 737 |
.. versionchanged:: 3.9 |
| 738 |
The :attr:`Traceback.total_nframe` attribute was added. |
| 739 |
|
| 740 |
.. method:: format(limit=None, most_recent_first=False) |
| 741 |
|
| 742 |
Format the traceback as a list of lines. Use the :mod:`linecache` module to |
| 743 |
retrieve lines from the source code. If *limit* is set, format the *limit* |
| 744 |
most recent frames if *limit* is positive. Otherwise, format the |
| 745 |
``abs(limit)`` oldest frames. If *most_recent_first* is ``True``, the order |
| 746 |
of the formatted frames is reversed, returning the most recent frame first |
| 747 |
instead of last. |
| 748 |
|
| 749 |
Similar to the :func:`traceback.format_tb` function, except that |
| 750 |
:meth:`.format` does not include newlines. |
| 751 |
|
| 752 |
Example:: |
| 753 |
|
| 754 |
print("Traceback (most recent call first):") |
| 755 |
for line in traceback: |
| 756 |
print(line) |
| 757 |
|
| 758 |
Output:: |
| 759 |
|
| 760 |
Traceback (most recent call first): |
| 761 |
File "test.py", line 9 |
| 762 |
obj = Object() |
| 763 |
File "test.py", line 12 |
| 764 |
tb = tracemalloc.get_object_traceback(f()) |