blob: 20f668c72820282bf31f896f01e1f59305dd1951 [file] [log] [blame]
Victor Stinnered3b0bc2013-11-23 12:27:24 +01001:mod:`tracemalloc` --- Trace memory allocations
2===============================================
3
4.. module:: tracemalloc
5 :synopsis: Trace memory allocations.
6
R David Murray6d5cb072013-12-20 14:48:50 -05007.. versionadded:: 3.4
8
Terry Jan Reedyfa089b92016-06-11 15:02:54 -04009**Source code:** :source:`Lib/tracemalloc.py`
10
11--------------
12
Victor Stinnered3b0bc2013-11-23 12:27:24 +010013The tracemalloc module is a debug tool to trace memory blocks allocated by
14Python. 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
21To trace most memory blocks allocated by Python, the module should be started
22as early as possible by setting the :envvar:`PYTHONTRACEMALLOC` environment
23variable to ``1``, or by using :option:`-X` ``tracemalloc`` command line
24option. The :func:`tracemalloc.start` function can be called at runtime to
25start tracing Python memory allocations.
26
27By default, a trace of an allocated memory block only stores the most recent
28frame (1 frame). To store 25 frames at startup: set the
29:envvar:`PYTHONTRACEMALLOC` environment variable to ``25``, or use the
Victor Stinner3728d6c2013-11-23 12:37:20 +010030:option:`-X` ``tracemalloc=25`` command line option.
Victor Stinnered3b0bc2013-11-23 12:27:24 +010031
Victor Stinnered3b0bc2013-11-23 12:27:24 +010032
33Examples
Georg Brandl717e0282014-10-31 10:21:07 +010034--------
Victor Stinnered3b0bc2013-11-23 12:27:24 +010035
36Display the top 10
Georg Brandl717e0282014-10-31 10:21:07 +010037^^^^^^^^^^^^^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +010038
39Display 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
55Example 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
Victor Stinner440d7032016-12-30 02:14:59 +010069We can see that Python loaded ``4855 KiB`` data (bytecode and constants) from
Victor Stinnered3b0bc2013-11-23 12:27:24 +010070modules and that the :mod:`collections` module allocated ``244 KiB`` to build
71:class:`~collections.namedtuple` types.
72
73See :meth:`Snapshot.statistics` for more options.
74
75
76Compute differences
Georg Brandl717e0282014-10-31 10:21:07 +010077^^^^^^^^^^^^^^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +010078
79Take 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
95Example 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
Victor Stinner440d7032016-12-30 02:14:59 +0100109We can see that Python has loaded ``8173 KiB`` of module data (bytecode and
110constants), and that this is ``4428 KiB`` more than had been loaded before the
Victor Stinner00773df2013-11-26 00:40:10 +0100111tests, when the previous snapshot was taken. Similarly, the :mod:`linecache`
112module has cached ``940 KiB`` of Python source code to format tracebacks, all
113of it since the previous snapshot.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100114
115If the system has little free memory, snapshots can be written on disk using
116the :meth:`Snapshot.dump` method to analyze the snapshot offline. Then use the
117:meth:`Snapshot.load` method reload the snapshot.
118
119
120Get the traceback of a memory block
Georg Brandl717e0282014-10-31 10:21:07 +0100121^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100122
123Code to display the traceback of the biggest memory block::
124
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100125 import tracemalloc
126
Victor Stinner3728d6c2013-11-23 12:37:20 +0100127 # Store 25 frames
128 tracemalloc.start(25)
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100129
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))
Victor Stinner23f628d2014-02-16 23:53:38 +0100138 for line in stat.traceback.format():
139 print(line)
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100140
141Example 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
Victor Stinner00773df2013-11-26 00:40:10 +0100178We can see that the most memory was allocated in the :mod:`importlib` module to
Victor Stinner440d7032016-12-30 02:14:59 +0100179load data (bytecode and constants) from modules: ``870.1 KiB``. The traceback is
Victor Stinner00773df2013-11-26 00:40:10 +0100180where the :mod:`importlib` loaded data most recently: on the ``import pdb``
181line of the :mod:`doctest` module. The traceback may change if a new module is
182loaded.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100183
184
185Pretty top
Georg Brandl717e0282014-10-31 10:21:07 +0100186^^^^^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100187
188Code to display the 10 lines allocating the most memory with a pretty output,
189ignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files::
190
Victor Stinner637d2e92014-03-11 08:12:48 +0100191 import linecache
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100192 import os
193 import tracemalloc
194
Victor Stinner440d7032016-12-30 02:14:59 +0100195 def display_top(snapshot, key_type='lineno', limit=10):
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100196 snapshot = snapshot.filter_traces((
197 tracemalloc.Filter(False, "<frozen importlib._bootstrap>"),
198 tracemalloc.Filter(False, "<unknown>"),
199 ))
Victor Stinner440d7032016-12-30 02:14:59 +0100200 top_stats = snapshot.statistics(key_type)
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100201
202 print("Top %s lines" % limit)
203 for index, stat in enumerate(top_stats[:limit], 1):
204 frame = stat.traceback[0]
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100205 print("#%s: %s:%s: %.1f KiB"
Adam Johnsond06eec22020-03-10 18:18:50 +0000206 % (index, frame.filename, frame.lineno, stat.size / 1024))
Victor Stinner637d2e92014-03-11 08:12:48 +0100207 line = linecache.getline(frame.filename, frame.lineno).strip()
208 if line:
209 print(' %s' % line)
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100210
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()
Victor Stinnerf70200e2014-03-03 11:57:57 +0100223 display_top(snapshot)
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100224
225Example of output of the Python test suite::
226
Victor Stinner637d2e92014-03-11 08:12:48 +0100227 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
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100249
250See :meth:`Snapshot.statistics` for more options.
251
Huon Wilson8b626442020-05-23 00:18:51 +1000252Record the current and peak size of all traced memory blocks
253~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
254
255The following code computes two sums like ``0 + 1 + 2 + ...`` inefficiently, by
256creating a list of those numbers. This list consumes a lot of memory
257temporarily. We can use :func:`get_traced_memory` and :func:`reset_peak` to
258observe the small memory usage after the sum is computed as well as the peak
259memory 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
280Output::
281
282 first_size=664, first_peak=3592984
283 second_size=804, second_peak=29704
284
285Using :func:`reset_peak` ensured we could accurately record the peak during the
286computation of ``small_sum``, even though it is much smaller than the overall
287peak 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
289computation ``large_sum`` (that is, equal to ``first_peak``). In this case,
290both peaks are much higher than the final memory usage, and which suggests we
291could optimise (by removing the unnecessary call to :class:`list`, and writing
292``sum(range(...))``).
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100293
294API
Georg Brandl717e0282014-10-31 10:21:07 +0100295---
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100296
297Functions
Georg Brandl717e0282014-10-31 10:21:07 +0100298^^^^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100299
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
Victor Stinner3728d6c2013-11-23 12:37:20 +0100321 The :mod:`tracemalloc` module must be tracing memory allocations to
322 get the limit, otherwise an exception is raised.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100323
Victor Stinner3728d6c2013-11-23 12:37:20 +0100324 The limit is set by the :func:`start` function.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100325
326
327.. function:: get_traced_memory()
328
Victor Stinner3c0481d2013-11-27 21:39:49 +0100329 Get the current size and peak size of memory blocks traced by the
330 :mod:`tracemalloc` module as a tuple: ``(current: int, peak: int)``.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100331
332
Huon Wilson8b626442020-05-23 00:18:51 +1000333.. 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
Huon Wilson39de8e42020-06-02 03:26:33 +1000348 .. versionadded:: 3.9
Huon Wilson8b626442020-05-23 00:18:51 +1000349
350
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100351.. 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
Victor Stinner3728d6c2013-11-23 12:37:20 +0100366.. function:: start(nframe: int=1)
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100367
Victor Stinner3728d6c2013-11-23 12:37:20 +0100368 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``.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100372
Julien Danjou8d59eb12019-10-15 14:00:16 +0200373 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
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100376 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``
Victor Stinner3728d6c2013-11-23 12:37:20 +0100386 command line option can be used to start tracing at startup.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100387
Victor Stinner3728d6c2013-11-23 12:37:20 +0100388 See also :func:`stop`, :func:`is_tracing` and :func:`get_traceback_limit`
389 functions.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100390
391
392.. function:: stop()
393
394 Stop tracing Python memory allocations: uninstall hooks on Python memory
Victor Stinner00773df2013-11-26 00:40:10 +0100395 allocators. Also clears all previously collected traces of memory blocks
396 allocated by Python.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100397
398 Call :func:`take_snapshot` function to take a snapshot of traces before
399 clearing them.
400
Victor Stinner00773df2013-11-26 00:40:10 +0100401 See also :func:`start`, :func:`is_tracing` and :func:`clear_traces`
402 functions.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100403
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
Victor Stinner3728d6c2013-11-23 12:37:20 +0100414 the *nframe* parameter of the :func:`start` function to store more frames.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100415
416 The :mod:`tracemalloc` module must be tracing memory allocations to take a
Donald Stufft8b852f12014-05-20 12:58:38 -0400417 snapshot, see the :func:`start` function.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100418
419 See also the :func:`get_object_traceback` function.
420
421
Victor Stinnere492ae52016-03-22 12:58:23 +0100422DomainFilter
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
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100444Filter
Georg Brandl717e0282014-10-31 10:21:07 +0100445^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100446
Victor Stinnere492ae52016-03-22 12:58:23 +0100447.. class:: Filter(inclusive: bool, filename_pattern: str, lineno: int=None, all_frames: bool=False, domain: int=None)
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100448
449 Filter on traces of memory blocks.
450
451 See the :func:`fnmatch.fnmatch` function for the syntax of
Brett Cannonf299abd2015-04-13 14:21:02 -0400452 *filename_pattern*. The ``'.pyc'`` file extension is
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100453 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
Brett Cannonf299abd2015-04-13 14:21:02 -0400463
464 .. versionchanged:: 3.5
465 The ``'.pyo'`` file extension is no longer replaced with ``'.py'``.
466
Victor Stinnere492ae52016-03-22 12:58:23 +0100467 .. 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
Victor Stinner5ea4c062017-06-20 17:46:36 +0200475 tracemalloc uses the domain ``0`` to trace memory allocations made by
476 Python. C extensions can use other domains to trace other resources.
477
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100478 .. attribute:: inclusive
479
Victor Stinnere492ae52016-03-22 12:58:23 +0100480 If *inclusive* is ``True`` (include), only match memory blocks allocated
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100481 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
Victor Stinnere492ae52016-03-22 12:58:23 +0100495 Filename pattern of the filter (``str``). Read-only property.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100496
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
Victor Stinner5362abf2013-11-27 23:39:55 +0100502 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.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100505
506
507Frame
Georg Brandl717e0282014-10-31 10:21:07 +0100508^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100509
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
525Snapshot
Georg Brandl717e0282014-10-31 10:21:07 +0100526^^^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100527
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
Victor Stinner440d7032016-12-30 02:14:59 +0100534 .. method:: compare_to(old_snapshot: Snapshot, key_type: str, cumulative: bool=False)
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100535
536 Compute the differences with an old snapshot. Get statistics as a sorted
Victor Stinner440d7032016-12-30 02:14:59 +0100537 list of :class:`StatisticDiff` instances grouped by *key_type*.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100538
Victor Stinner440d7032016-12-30 02:14:59 +0100539 See the :meth:`Snapshot.statistics` method for *key_type* and *cumulative*
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100540 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`
Victor Stinnere492ae52016-03-22 12:58:23 +0100558 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.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100561
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
Martin Panter1f1177d2015-10-31 11:48:53 +0000564 filter matches it.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100565
Victor Stinnere492ae52016-03-22 12:58:23 +0100566 .. versionchanged:: 3.6
567 :class:`DomainFilter` instances are now also accepted in *filters*.
568
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100569
570 .. classmethod:: load(filename)
571
572 Load a snapshot from a file.
573
574 See also :meth:`dump`.
575
576
Victor Stinner440d7032016-12-30 02:14:59 +0100577 .. method:: statistics(key_type: str, cumulative: bool=False)
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100578
579 Get statistics as a sorted list of :class:`Statistic` instances grouped
Victor Stinner440d7032016-12-30 02:14:59 +0100580 by *key_type*:
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100581
582 ===================== ========================
Victor Stinner440d7032016-12-30 02:14:59 +0100583 key_type description
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100584 ===================== ========================
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.
Victor Stinner440d7032016-12-30 02:14:59 +0100592 The cumulative mode can only be used with *key_type* equals to
Victor Stinner8e3708d2013-11-26 00:45:47 +0100593 ``'filename'`` and ``'lineno'``.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100594
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
614Statistic
Georg Brandl717e0282014-10-31 10:21:07 +0100615^^^^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100616
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
639StatisticDiff
Georg Brandl717e0282014-10-31 10:21:07 +0100640^^^^^^^^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100641
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
678Trace
Georg Brandl717e0282014-10-31 10:21:07 +0100679^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100680
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
Victor Stinner5ea4c062017-06-20 17:46:36 +0200688 .. 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
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100698 .. 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
708Traceback
Georg Brandl717e0282014-10-31 10:21:07 +0100709^^^^^^^^^
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100710
711.. class:: Traceback
712
Jesse-Bakker706e10b2017-11-30 00:05:07 +0100713 Sequence of :class:`Frame` instances sorted from the oldest frame to the
714 most recent frame.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100715
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.
Julien Danjou8d59eb12019-10-15 14:00:16 +0200722 The original number of frames of the traceback is stored in the
723 :attr:`Traceback.total_nframe` attribute. That allows to know if a traceback
724 has been truncated by the traceback limit.
Victor Stinnered3b0bc2013-11-23 12:27:24 +0100725
726 The :attr:`Trace.traceback` attribute is an instance of :class:`Traceback`
727 instance.
728
Jesse-Bakker706e10b2017-11-30 00:05:07 +0100729 .. versionchanged:: 3.7
730 Frames are now sorted from the oldest to the most recent, instead of most recent to oldest.
Victor Stinner23f628d2014-02-16 23:53:38 +0100731
Julien Danjou8d59eb12019-10-15 14:00:16 +0200732 .. attribute:: total_nframe
733
734 Total number of frames that composed the traceback before truncation.
735 This attribute can be set to ``None`` if the information is not
736 available.
737
738 .. versionchanged:: 3.9
739 The :attr:`Traceback.total_nframe` attribute was added.
740
Jesse-Bakker706e10b2017-11-30 00:05:07 +0100741 .. method:: format(limit=None, most_recent_first=False)
742
743 Format the traceback as a list of lines with newlines. Use the
744 :mod:`linecache` module to retrieve lines from the source code.
745 If *limit* is set, format the *limit* most recent frames if *limit*
746 is positive. Otherwise, format the ``abs(limit)`` oldest frames.
747 If *most_recent_first* is ``True``, the order of the formatted frames
748 is reversed, returning the most recent frame first instead of last.
Victor Stinner23f628d2014-02-16 23:53:38 +0100749
750 Similar to the :func:`traceback.format_tb` function, except that
Martin Panterd5db1472016-02-08 01:34:09 +0000751 :meth:`.format` does not include newlines.
Victor Stinner23f628d2014-02-16 23:53:38 +0100752
753 Example::
754
755 print("Traceback (most recent call first):")
756 for line in traceback:
757 print(line)
758
759 Output::
760
761 Traceback (most recent call first):
762 File "test.py", line 9
763 obj = Object()
764 File "test.py", line 12
765 tb = tracemalloc.get_object_traceback(f())