Debian Codegraph @

Doc/library/tracemalloc.rst

raw
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())