17db96d56Sopenharmony_ci:mod:`tracemalloc` --- Trace memory allocations
27db96d56Sopenharmony_ci===============================================
37db96d56Sopenharmony_ci
47db96d56Sopenharmony_ci.. module:: tracemalloc
57db96d56Sopenharmony_ci   :synopsis: Trace memory allocations.
67db96d56Sopenharmony_ci
77db96d56Sopenharmony_ci.. versionadded:: 3.4
87db96d56Sopenharmony_ci
97db96d56Sopenharmony_ci**Source code:** :source:`Lib/tracemalloc.py`
107db96d56Sopenharmony_ci
117db96d56Sopenharmony_ci--------------
127db96d56Sopenharmony_ci
137db96d56Sopenharmony_ciThe tracemalloc module is a debug tool to trace memory blocks allocated by
147db96d56Sopenharmony_ciPython. It provides the following information:
157db96d56Sopenharmony_ci
167db96d56Sopenharmony_ci* Traceback where an object was allocated
177db96d56Sopenharmony_ci* Statistics on allocated memory blocks per filename and per line number:
187db96d56Sopenharmony_ci  total size, number and average size of allocated memory blocks
197db96d56Sopenharmony_ci* Compute the differences between two snapshots to detect memory leaks
207db96d56Sopenharmony_ci
217db96d56Sopenharmony_ciTo trace most memory blocks allocated by Python, the module should be started
227db96d56Sopenharmony_cias early as possible by setting the :envvar:`PYTHONTRACEMALLOC` environment
237db96d56Sopenharmony_civariable to ``1``, or by using :option:`-X` ``tracemalloc`` command line
247db96d56Sopenharmony_cioption. The :func:`tracemalloc.start` function can be called at runtime to
257db96d56Sopenharmony_cistart tracing Python memory allocations.
267db96d56Sopenharmony_ci
277db96d56Sopenharmony_ciBy default, a trace of an allocated memory block only stores the most recent
287db96d56Sopenharmony_ciframe (1 frame). To store 25 frames at startup: set the
297db96d56Sopenharmony_ci:envvar:`PYTHONTRACEMALLOC` environment variable to ``25``, or use the
307db96d56Sopenharmony_ci:option:`-X` ``tracemalloc=25`` command line option.
317db96d56Sopenharmony_ci
327db96d56Sopenharmony_ci
337db96d56Sopenharmony_ciExamples
347db96d56Sopenharmony_ci--------
357db96d56Sopenharmony_ci
367db96d56Sopenharmony_ciDisplay the top 10
377db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^
387db96d56Sopenharmony_ci
397db96d56Sopenharmony_ciDisplay the 10 files allocating the most memory::
407db96d56Sopenharmony_ci
417db96d56Sopenharmony_ci    import tracemalloc
427db96d56Sopenharmony_ci
437db96d56Sopenharmony_ci    tracemalloc.start()
447db96d56Sopenharmony_ci
457db96d56Sopenharmony_ci    # ... run your application ...
467db96d56Sopenharmony_ci
477db96d56Sopenharmony_ci    snapshot = tracemalloc.take_snapshot()
487db96d56Sopenharmony_ci    top_stats = snapshot.statistics('lineno')
497db96d56Sopenharmony_ci
507db96d56Sopenharmony_ci    print("[ Top 10 ]")
517db96d56Sopenharmony_ci    for stat in top_stats[:10]:
527db96d56Sopenharmony_ci        print(stat)
537db96d56Sopenharmony_ci
547db96d56Sopenharmony_ci
557db96d56Sopenharmony_ciExample of output of the Python test suite::
567db96d56Sopenharmony_ci
577db96d56Sopenharmony_ci    [ Top 10 ]
587db96d56Sopenharmony_ci    <frozen importlib._bootstrap>:716: size=4855 KiB, count=39328, average=126 B
597db96d56Sopenharmony_ci    <frozen importlib._bootstrap>:284: size=521 KiB, count=3199, average=167 B
607db96d56Sopenharmony_ci    /usr/lib/python3.4/collections/__init__.py:368: size=244 KiB, count=2315, average=108 B
617db96d56Sopenharmony_ci    /usr/lib/python3.4/unittest/case.py:381: size=185 KiB, count=779, average=243 B
627db96d56Sopenharmony_ci    /usr/lib/python3.4/unittest/case.py:402: size=154 KiB, count=378, average=416 B
637db96d56Sopenharmony_ci    /usr/lib/python3.4/abc.py:133: size=88.7 KiB, count=347, average=262 B
647db96d56Sopenharmony_ci    <frozen importlib._bootstrap>:1446: size=70.4 KiB, count=911, average=79 B
657db96d56Sopenharmony_ci    <frozen importlib._bootstrap>:1454: size=52.0 KiB, count=25, average=2131 B
667db96d56Sopenharmony_ci    <string>:5: size=49.7 KiB, count=148, average=344 B
677db96d56Sopenharmony_ci    /usr/lib/python3.4/sysconfig.py:411: size=48.0 KiB, count=1, average=48.0 KiB
687db96d56Sopenharmony_ci
697db96d56Sopenharmony_ciWe can see that Python loaded ``4855 KiB`` data (bytecode and constants) from
707db96d56Sopenharmony_cimodules and that the :mod:`collections` module allocated ``244 KiB`` to build
717db96d56Sopenharmony_ci:class:`~collections.namedtuple` types.
727db96d56Sopenharmony_ci
737db96d56Sopenharmony_ciSee :meth:`Snapshot.statistics` for more options.
747db96d56Sopenharmony_ci
757db96d56Sopenharmony_ci
767db96d56Sopenharmony_ciCompute differences
777db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^^
787db96d56Sopenharmony_ci
797db96d56Sopenharmony_ciTake two snapshots and display the differences::
807db96d56Sopenharmony_ci
817db96d56Sopenharmony_ci    import tracemalloc
827db96d56Sopenharmony_ci    tracemalloc.start()
837db96d56Sopenharmony_ci    # ... start your application ...
847db96d56Sopenharmony_ci
857db96d56Sopenharmony_ci    snapshot1 = tracemalloc.take_snapshot()
867db96d56Sopenharmony_ci    # ... call the function leaking memory ...
877db96d56Sopenharmony_ci    snapshot2 = tracemalloc.take_snapshot()
887db96d56Sopenharmony_ci
897db96d56Sopenharmony_ci    top_stats = snapshot2.compare_to(snapshot1, 'lineno')
907db96d56Sopenharmony_ci
917db96d56Sopenharmony_ci    print("[ Top 10 differences ]")
927db96d56Sopenharmony_ci    for stat in top_stats[:10]:
937db96d56Sopenharmony_ci        print(stat)
947db96d56Sopenharmony_ci
957db96d56Sopenharmony_ciExample of output before/after running some tests of the Python test suite::
967db96d56Sopenharmony_ci
977db96d56Sopenharmony_ci    [ Top 10 differences ]
987db96d56Sopenharmony_ci    <frozen importlib._bootstrap>:716: size=8173 KiB (+4428 KiB), count=71332 (+39369), average=117 B
997db96d56Sopenharmony_ci    /usr/lib/python3.4/linecache.py:127: size=940 KiB (+940 KiB), count=8106 (+8106), average=119 B
1007db96d56Sopenharmony_ci    /usr/lib/python3.4/unittest/case.py:571: size=298 KiB (+298 KiB), count=589 (+589), average=519 B
1017db96d56Sopenharmony_ci    <frozen importlib._bootstrap>:284: size=1005 KiB (+166 KiB), count=7423 (+1526), average=139 B
1027db96d56Sopenharmony_ci    /usr/lib/python3.4/mimetypes.py:217: size=112 KiB (+112 KiB), count=1334 (+1334), average=86 B
1037db96d56Sopenharmony_ci    /usr/lib/python3.4/http/server.py:848: size=96.0 KiB (+96.0 KiB), count=1 (+1), average=96.0 KiB
1047db96d56Sopenharmony_ci    /usr/lib/python3.4/inspect.py:1465: size=83.5 KiB (+83.5 KiB), count=109 (+109), average=784 B
1057db96d56Sopenharmony_ci    /usr/lib/python3.4/unittest/mock.py:491: size=77.7 KiB (+77.7 KiB), count=143 (+143), average=557 B
1067db96d56Sopenharmony_ci    /usr/lib/python3.4/urllib/parse.py:476: size=71.8 KiB (+71.8 KiB), count=969 (+969), average=76 B
1077db96d56Sopenharmony_ci    /usr/lib/python3.4/contextlib.py:38: size=67.2 KiB (+67.2 KiB), count=126 (+126), average=546 B
1087db96d56Sopenharmony_ci
1097db96d56Sopenharmony_ciWe can see that Python has loaded ``8173 KiB`` of module data (bytecode and
1107db96d56Sopenharmony_ciconstants), and that this is ``4428 KiB`` more than had been loaded before the
1117db96d56Sopenharmony_citests, when the previous snapshot was taken. Similarly, the :mod:`linecache`
1127db96d56Sopenharmony_cimodule has cached ``940 KiB`` of Python source code to format tracebacks, all
1137db96d56Sopenharmony_ciof it since the previous snapshot.
1147db96d56Sopenharmony_ci
1157db96d56Sopenharmony_ciIf the system has little free memory, snapshots can be written on disk using
1167db96d56Sopenharmony_cithe :meth:`Snapshot.dump` method to analyze the snapshot offline. Then use the
1177db96d56Sopenharmony_ci:meth:`Snapshot.load` method reload the snapshot.
1187db96d56Sopenharmony_ci
1197db96d56Sopenharmony_ci
1207db96d56Sopenharmony_ciGet the traceback of a memory block
1217db96d56Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1227db96d56Sopenharmony_ci
1237db96d56Sopenharmony_ciCode to display the traceback of the biggest memory block::
1247db96d56Sopenharmony_ci
1257db96d56Sopenharmony_ci    import tracemalloc
1267db96d56Sopenharmony_ci
1277db96d56Sopenharmony_ci    # Store 25 frames
1287db96d56Sopenharmony_ci    tracemalloc.start(25)
1297db96d56Sopenharmony_ci
1307db96d56Sopenharmony_ci    # ... run your application ...
1317db96d56Sopenharmony_ci
1327db96d56Sopenharmony_ci    snapshot = tracemalloc.take_snapshot()
1337db96d56Sopenharmony_ci    top_stats = snapshot.statistics('traceback')
1347db96d56Sopenharmony_ci
1357db96d56Sopenharmony_ci    # pick the biggest memory block
1367db96d56Sopenharmony_ci    stat = top_stats[0]
1377db96d56Sopenharmony_ci    print("%s memory blocks: %.1f KiB" % (stat.count, stat.size / 1024))
1387db96d56Sopenharmony_ci    for line in stat.traceback.format():
1397db96d56Sopenharmony_ci        print(line)
1407db96d56Sopenharmony_ci
1417db96d56Sopenharmony_ciExample of output of the Python test suite (traceback limited to 25 frames)::
1427db96d56Sopenharmony_ci
1437db96d56Sopenharmony_ci    903 memory blocks: 870.1 KiB
1447db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 716
1457db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 1036
1467db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 934
1477db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 1068
1487db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 619
1497db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 1581
1507db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 1614
1517db96d56Sopenharmony_ci      File "/usr/lib/python3.4/doctest.py", line 101
1527db96d56Sopenharmony_ci        import pdb
1537db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 284
1547db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 938
1557db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 1068
1567db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 619
1577db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 1581
1587db96d56Sopenharmony_ci      File "<frozen importlib._bootstrap>", line 1614
1597db96d56Sopenharmony_ci      File "/usr/lib/python3.4/test/support/__init__.py", line 1728
1607db96d56Sopenharmony_ci        import doctest
1617db96d56Sopenharmony_ci      File "/usr/lib/python3.4/test/test_pickletools.py", line 21
1627db96d56Sopenharmony_ci        support.run_doctest(pickletools)
1637db96d56Sopenharmony_ci      File "/usr/lib/python3.4/test/regrtest.py", line 1276
1647db96d56Sopenharmony_ci        test_runner()
1657db96d56Sopenharmony_ci      File "/usr/lib/python3.4/test/regrtest.py", line 976
1667db96d56Sopenharmony_ci        display_failure=not verbose)
1677db96d56Sopenharmony_ci      File "/usr/lib/python3.4/test/regrtest.py", line 761
1687db96d56Sopenharmony_ci        match_tests=ns.match_tests)
1697db96d56Sopenharmony_ci      File "/usr/lib/python3.4/test/regrtest.py", line 1563
1707db96d56Sopenharmony_ci        main()
1717db96d56Sopenharmony_ci      File "/usr/lib/python3.4/test/__main__.py", line 3
1727db96d56Sopenharmony_ci        regrtest.main_in_temp_cwd()
1737db96d56Sopenharmony_ci      File "/usr/lib/python3.4/runpy.py", line 73
1747db96d56Sopenharmony_ci        exec(code, run_globals)
1757db96d56Sopenharmony_ci      File "/usr/lib/python3.4/runpy.py", line 160
1767db96d56Sopenharmony_ci        "__main__", fname, loader, pkg_name)
1777db96d56Sopenharmony_ci
1787db96d56Sopenharmony_ciWe can see that the most memory was allocated in the :mod:`importlib` module to
1797db96d56Sopenharmony_ciload data (bytecode and constants) from modules: ``870.1 KiB``. The traceback is
1807db96d56Sopenharmony_ciwhere the :mod:`importlib` loaded data most recently: on the ``import pdb``
1817db96d56Sopenharmony_ciline of the :mod:`doctest` module. The traceback may change if a new module is
1827db96d56Sopenharmony_ciloaded.
1837db96d56Sopenharmony_ci
1847db96d56Sopenharmony_ci
1857db96d56Sopenharmony_ciPretty top
1867db96d56Sopenharmony_ci^^^^^^^^^^
1877db96d56Sopenharmony_ci
1887db96d56Sopenharmony_ciCode to display the 10 lines allocating the most memory with a pretty output,
1897db96d56Sopenharmony_ciignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files::
1907db96d56Sopenharmony_ci
1917db96d56Sopenharmony_ci    import linecache
1927db96d56Sopenharmony_ci    import os
1937db96d56Sopenharmony_ci    import tracemalloc
1947db96d56Sopenharmony_ci
1957db96d56Sopenharmony_ci    def display_top(snapshot, key_type='lineno', limit=10):
1967db96d56Sopenharmony_ci        snapshot = snapshot.filter_traces((
1977db96d56Sopenharmony_ci            tracemalloc.Filter(False, "<frozen importlib._bootstrap>"),
1987db96d56Sopenharmony_ci            tracemalloc.Filter(False, "<unknown>"),
1997db96d56Sopenharmony_ci        ))
2007db96d56Sopenharmony_ci        top_stats = snapshot.statistics(key_type)
2017db96d56Sopenharmony_ci
2027db96d56Sopenharmony_ci        print("Top %s lines" % limit)
2037db96d56Sopenharmony_ci        for index, stat in enumerate(top_stats[:limit], 1):
2047db96d56Sopenharmony_ci            frame = stat.traceback[0]
2057db96d56Sopenharmony_ci            print("#%s: %s:%s: %.1f KiB"
2067db96d56Sopenharmony_ci                  % (index, frame.filename, frame.lineno, stat.size / 1024))
2077db96d56Sopenharmony_ci            line = linecache.getline(frame.filename, frame.lineno).strip()
2087db96d56Sopenharmony_ci            if line:
2097db96d56Sopenharmony_ci                print('    %s' % line)
2107db96d56Sopenharmony_ci
2117db96d56Sopenharmony_ci        other = top_stats[limit:]
2127db96d56Sopenharmony_ci        if other:
2137db96d56Sopenharmony_ci            size = sum(stat.size for stat in other)
2147db96d56Sopenharmony_ci            print("%s other: %.1f KiB" % (len(other), size / 1024))
2157db96d56Sopenharmony_ci        total = sum(stat.size for stat in top_stats)
2167db96d56Sopenharmony_ci        print("Total allocated size: %.1f KiB" % (total / 1024))
2177db96d56Sopenharmony_ci
2187db96d56Sopenharmony_ci    tracemalloc.start()
2197db96d56Sopenharmony_ci
2207db96d56Sopenharmony_ci    # ... run your application ...
2217db96d56Sopenharmony_ci
2227db96d56Sopenharmony_ci    snapshot = tracemalloc.take_snapshot()
2237db96d56Sopenharmony_ci    display_top(snapshot)
2247db96d56Sopenharmony_ci
2257db96d56Sopenharmony_ciExample of output of the Python test suite::
2267db96d56Sopenharmony_ci
2277db96d56Sopenharmony_ci    Top 10 lines
2287db96d56Sopenharmony_ci    #1: Lib/base64.py:414: 419.8 KiB
2297db96d56Sopenharmony_ci        _b85chars2 = [(a + b) for a in _b85chars for b in _b85chars]
2307db96d56Sopenharmony_ci    #2: Lib/base64.py:306: 419.8 KiB
2317db96d56Sopenharmony_ci        _a85chars2 = [(a + b) for a in _a85chars for b in _a85chars]
2327db96d56Sopenharmony_ci    #3: collections/__init__.py:368: 293.6 KiB
2337db96d56Sopenharmony_ci        exec(class_definition, namespace)
2347db96d56Sopenharmony_ci    #4: Lib/abc.py:133: 115.2 KiB
2357db96d56Sopenharmony_ci        cls = super().__new__(mcls, name, bases, namespace)
2367db96d56Sopenharmony_ci    #5: unittest/case.py:574: 103.1 KiB
2377db96d56Sopenharmony_ci        testMethod()
2387db96d56Sopenharmony_ci    #6: Lib/linecache.py:127: 95.4 KiB
2397db96d56Sopenharmony_ci        lines = fp.readlines()
2407db96d56Sopenharmony_ci    #7: urllib/parse.py:476: 71.8 KiB
2417db96d56Sopenharmony_ci        for a in _hexdig for b in _hexdig}
2427db96d56Sopenharmony_ci    #8: <string>:5: 62.0 KiB
2437db96d56Sopenharmony_ci    #9: Lib/_weakrefset.py:37: 60.0 KiB
2447db96d56Sopenharmony_ci        self.data = set()
2457db96d56Sopenharmony_ci    #10: Lib/base64.py:142: 59.8 KiB
2467db96d56Sopenharmony_ci        _b32tab2 = [a + b for a in _b32tab for b in _b32tab]
2477db96d56Sopenharmony_ci    6220 other: 3602.8 KiB
2487db96d56Sopenharmony_ci    Total allocated size: 5303.1 KiB
2497db96d56Sopenharmony_ci
2507db96d56Sopenharmony_ciSee :meth:`Snapshot.statistics` for more options.
2517db96d56Sopenharmony_ci
2527db96d56Sopenharmony_ciRecord the current and peak size of all traced memory blocks
2537db96d56Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2547db96d56Sopenharmony_ci
2557db96d56Sopenharmony_ciThe following code computes two sums like ``0 + 1 + 2 + ...`` inefficiently, by
2567db96d56Sopenharmony_cicreating a list of those numbers. This list consumes a lot of memory
2577db96d56Sopenharmony_citemporarily. We can use :func:`get_traced_memory` and :func:`reset_peak` to
2587db96d56Sopenharmony_ciobserve the small memory usage after the sum is computed as well as the peak
2597db96d56Sopenharmony_cimemory usage during the computations::
2607db96d56Sopenharmony_ci
2617db96d56Sopenharmony_ci  import tracemalloc
2627db96d56Sopenharmony_ci
2637db96d56Sopenharmony_ci  tracemalloc.start()
2647db96d56Sopenharmony_ci
2657db96d56Sopenharmony_ci  # Example code: compute a sum with a large temporary list
2667db96d56Sopenharmony_ci  large_sum = sum(list(range(100000)))
2677db96d56Sopenharmony_ci
2687db96d56Sopenharmony_ci  first_size, first_peak = tracemalloc.get_traced_memory()
2697db96d56Sopenharmony_ci
2707db96d56Sopenharmony_ci  tracemalloc.reset_peak()
2717db96d56Sopenharmony_ci
2727db96d56Sopenharmony_ci  # Example code: compute a sum with a small temporary list
2737db96d56Sopenharmony_ci  small_sum = sum(list(range(1000)))
2747db96d56Sopenharmony_ci
2757db96d56Sopenharmony_ci  second_size, second_peak = tracemalloc.get_traced_memory()
2767db96d56Sopenharmony_ci
2777db96d56Sopenharmony_ci  print(f"{first_size=}, {first_peak=}")
2787db96d56Sopenharmony_ci  print(f"{second_size=}, {second_peak=}")
2797db96d56Sopenharmony_ci
2807db96d56Sopenharmony_ciOutput::
2817db96d56Sopenharmony_ci
2827db96d56Sopenharmony_ci  first_size=664, first_peak=3592984
2837db96d56Sopenharmony_ci  second_size=804, second_peak=29704
2847db96d56Sopenharmony_ci
2857db96d56Sopenharmony_ciUsing :func:`reset_peak` ensured we could accurately record the peak during the
2867db96d56Sopenharmony_cicomputation of ``small_sum``, even though it is much smaller than the overall
2877db96d56Sopenharmony_cipeak size of memory blocks since the :func:`start` call. Without the call to
2887db96d56Sopenharmony_ci:func:`reset_peak`, ``second_peak`` would still be the peak from the
2897db96d56Sopenharmony_cicomputation ``large_sum`` (that is, equal to ``first_peak``). In this case,
2907db96d56Sopenharmony_ciboth peaks are much higher than the final memory usage, and which suggests we
2917db96d56Sopenharmony_cicould optimise (by removing the unnecessary call to :class:`list`, and writing
2927db96d56Sopenharmony_ci``sum(range(...))``).
2937db96d56Sopenharmony_ci
2947db96d56Sopenharmony_ciAPI
2957db96d56Sopenharmony_ci---
2967db96d56Sopenharmony_ci
2977db96d56Sopenharmony_ciFunctions
2987db96d56Sopenharmony_ci^^^^^^^^^
2997db96d56Sopenharmony_ci
3007db96d56Sopenharmony_ci.. function:: clear_traces()
3017db96d56Sopenharmony_ci
3027db96d56Sopenharmony_ci   Clear traces of memory blocks allocated by Python.
3037db96d56Sopenharmony_ci
3047db96d56Sopenharmony_ci   See also :func:`stop`.
3057db96d56Sopenharmony_ci
3067db96d56Sopenharmony_ci
3077db96d56Sopenharmony_ci.. function:: get_object_traceback(obj)
3087db96d56Sopenharmony_ci
3097db96d56Sopenharmony_ci   Get the traceback where the Python object *obj* was allocated.
3107db96d56Sopenharmony_ci   Return a :class:`Traceback` instance, or ``None`` if the :mod:`tracemalloc`
3117db96d56Sopenharmony_ci   module is not tracing memory allocations or did not trace the allocation of
3127db96d56Sopenharmony_ci   the object.
3137db96d56Sopenharmony_ci
3147db96d56Sopenharmony_ci   See also :func:`gc.get_referrers` and :func:`sys.getsizeof` functions.
3157db96d56Sopenharmony_ci
3167db96d56Sopenharmony_ci
3177db96d56Sopenharmony_ci.. function:: get_traceback_limit()
3187db96d56Sopenharmony_ci
3197db96d56Sopenharmony_ci   Get the maximum number of frames stored in the traceback of a trace.
3207db96d56Sopenharmony_ci
3217db96d56Sopenharmony_ci   The :mod:`tracemalloc` module must be tracing memory allocations to
3227db96d56Sopenharmony_ci   get the limit, otherwise an exception is raised.
3237db96d56Sopenharmony_ci
3247db96d56Sopenharmony_ci   The limit is set by the :func:`start` function.
3257db96d56Sopenharmony_ci
3267db96d56Sopenharmony_ci
3277db96d56Sopenharmony_ci.. function:: get_traced_memory()
3287db96d56Sopenharmony_ci
3297db96d56Sopenharmony_ci   Get the current size and peak size of memory blocks traced by the
3307db96d56Sopenharmony_ci   :mod:`tracemalloc` module as a tuple: ``(current: int, peak: int)``.
3317db96d56Sopenharmony_ci
3327db96d56Sopenharmony_ci
3337db96d56Sopenharmony_ci.. function:: reset_peak()
3347db96d56Sopenharmony_ci
3357db96d56Sopenharmony_ci   Set the peak size of memory blocks traced by the :mod:`tracemalloc` module
3367db96d56Sopenharmony_ci   to the current size.
3377db96d56Sopenharmony_ci
3387db96d56Sopenharmony_ci   Do nothing if the :mod:`tracemalloc` module is not tracing memory
3397db96d56Sopenharmony_ci   allocations.
3407db96d56Sopenharmony_ci
3417db96d56Sopenharmony_ci   This function only modifies the recorded peak size, and does not modify or
3427db96d56Sopenharmony_ci   clear any traces, unlike :func:`clear_traces`. Snapshots taken with
3437db96d56Sopenharmony_ci   :func:`take_snapshot` before a call to :func:`reset_peak` can be
3447db96d56Sopenharmony_ci   meaningfully compared to snapshots taken after the call.
3457db96d56Sopenharmony_ci
3467db96d56Sopenharmony_ci   See also :func:`get_traced_memory`.
3477db96d56Sopenharmony_ci
3487db96d56Sopenharmony_ci   .. versionadded:: 3.9
3497db96d56Sopenharmony_ci
3507db96d56Sopenharmony_ci
3517db96d56Sopenharmony_ci.. function:: get_tracemalloc_memory()
3527db96d56Sopenharmony_ci
3537db96d56Sopenharmony_ci   Get the memory usage in bytes of the :mod:`tracemalloc` module used to store
3547db96d56Sopenharmony_ci   traces of memory blocks.
3557db96d56Sopenharmony_ci   Return an :class:`int`.
3567db96d56Sopenharmony_ci
3577db96d56Sopenharmony_ci
3587db96d56Sopenharmony_ci.. function:: is_tracing()
3597db96d56Sopenharmony_ci
3607db96d56Sopenharmony_ci    ``True`` if the :mod:`tracemalloc` module is tracing Python memory
3617db96d56Sopenharmony_ci    allocations, ``False`` otherwise.
3627db96d56Sopenharmony_ci
3637db96d56Sopenharmony_ci    See also :func:`start` and :func:`stop` functions.
3647db96d56Sopenharmony_ci
3657db96d56Sopenharmony_ci
3667db96d56Sopenharmony_ci.. function:: start(nframe: int=1)
3677db96d56Sopenharmony_ci
3687db96d56Sopenharmony_ci   Start tracing Python memory allocations: install hooks on Python memory
3697db96d56Sopenharmony_ci   allocators. Collected tracebacks of traces will be limited to *nframe*
3707db96d56Sopenharmony_ci   frames. By default, a trace of a memory block only stores the most recent
3717db96d56Sopenharmony_ci   frame: the limit is ``1``. *nframe* must be greater or equal to ``1``.
3727db96d56Sopenharmony_ci
3737db96d56Sopenharmony_ci   You can still read the original number of total frames that composed the
3747db96d56Sopenharmony_ci   traceback by looking at the :attr:`Traceback.total_nframe` attribute.
3757db96d56Sopenharmony_ci
3767db96d56Sopenharmony_ci   Storing more than ``1`` frame is only useful to compute statistics grouped
3777db96d56Sopenharmony_ci   by ``'traceback'`` or to compute cumulative statistics: see the
3787db96d56Sopenharmony_ci   :meth:`Snapshot.compare_to` and :meth:`Snapshot.statistics` methods.
3797db96d56Sopenharmony_ci
3807db96d56Sopenharmony_ci   Storing more frames increases the memory and CPU overhead of the
3817db96d56Sopenharmony_ci   :mod:`tracemalloc` module. Use the :func:`get_tracemalloc_memory` function
3827db96d56Sopenharmony_ci   to measure how much memory is used by the :mod:`tracemalloc` module.
3837db96d56Sopenharmony_ci
3847db96d56Sopenharmony_ci   The :envvar:`PYTHONTRACEMALLOC` environment variable
3857db96d56Sopenharmony_ci   (``PYTHONTRACEMALLOC=NFRAME``) and the :option:`-X` ``tracemalloc=NFRAME``
3867db96d56Sopenharmony_ci   command line option can be used to start tracing at startup.
3877db96d56Sopenharmony_ci
3887db96d56Sopenharmony_ci   See also :func:`stop`, :func:`is_tracing` and :func:`get_traceback_limit`
3897db96d56Sopenharmony_ci   functions.
3907db96d56Sopenharmony_ci
3917db96d56Sopenharmony_ci
3927db96d56Sopenharmony_ci.. function:: stop()
3937db96d56Sopenharmony_ci
3947db96d56Sopenharmony_ci   Stop tracing Python memory allocations: uninstall hooks on Python memory
3957db96d56Sopenharmony_ci   allocators. Also clears all previously collected traces of memory blocks
3967db96d56Sopenharmony_ci   allocated by Python.
3977db96d56Sopenharmony_ci
3987db96d56Sopenharmony_ci   Call :func:`take_snapshot` function to take a snapshot of traces before
3997db96d56Sopenharmony_ci   clearing them.
4007db96d56Sopenharmony_ci
4017db96d56Sopenharmony_ci   See also :func:`start`, :func:`is_tracing` and :func:`clear_traces`
4027db96d56Sopenharmony_ci   functions.
4037db96d56Sopenharmony_ci
4047db96d56Sopenharmony_ci
4057db96d56Sopenharmony_ci.. function:: take_snapshot()
4067db96d56Sopenharmony_ci
4077db96d56Sopenharmony_ci   Take a snapshot of traces of memory blocks allocated by Python. Return a new
4087db96d56Sopenharmony_ci   :class:`Snapshot` instance.
4097db96d56Sopenharmony_ci
4107db96d56Sopenharmony_ci   The snapshot does not include memory blocks allocated before the
4117db96d56Sopenharmony_ci   :mod:`tracemalloc` module started to trace memory allocations.
4127db96d56Sopenharmony_ci
4137db96d56Sopenharmony_ci   Tracebacks of traces are limited to :func:`get_traceback_limit` frames. Use
4147db96d56Sopenharmony_ci   the *nframe* parameter of the :func:`start` function to store more frames.
4157db96d56Sopenharmony_ci
4167db96d56Sopenharmony_ci   The :mod:`tracemalloc` module must be tracing memory allocations to take a
4177db96d56Sopenharmony_ci   snapshot, see the :func:`start` function.
4187db96d56Sopenharmony_ci
4197db96d56Sopenharmony_ci   See also the :func:`get_object_traceback` function.
4207db96d56Sopenharmony_ci
4217db96d56Sopenharmony_ci
4227db96d56Sopenharmony_ciDomainFilter
4237db96d56Sopenharmony_ci^^^^^^^^^^^^
4247db96d56Sopenharmony_ci
4257db96d56Sopenharmony_ci.. class:: DomainFilter(inclusive: bool, domain: int)
4267db96d56Sopenharmony_ci
4277db96d56Sopenharmony_ci   Filter traces of memory blocks by their address space (domain).
4287db96d56Sopenharmony_ci
4297db96d56Sopenharmony_ci   .. versionadded:: 3.6
4307db96d56Sopenharmony_ci
4317db96d56Sopenharmony_ci   .. attribute:: inclusive
4327db96d56Sopenharmony_ci
4337db96d56Sopenharmony_ci      If *inclusive* is ``True`` (include), match memory blocks allocated
4347db96d56Sopenharmony_ci      in the address space :attr:`domain`.
4357db96d56Sopenharmony_ci
4367db96d56Sopenharmony_ci      If *inclusive* is ``False`` (exclude), match memory blocks not allocated
4377db96d56Sopenharmony_ci      in the address space :attr:`domain`.
4387db96d56Sopenharmony_ci
4397db96d56Sopenharmony_ci   .. attribute:: domain
4407db96d56Sopenharmony_ci
4417db96d56Sopenharmony_ci      Address space of a memory block (``int``). Read-only property.
4427db96d56Sopenharmony_ci
4437db96d56Sopenharmony_ci
4447db96d56Sopenharmony_ciFilter
4457db96d56Sopenharmony_ci^^^^^^
4467db96d56Sopenharmony_ci
4477db96d56Sopenharmony_ci.. class:: Filter(inclusive: bool, filename_pattern: str, lineno: int=None, all_frames: bool=False, domain: int=None)
4487db96d56Sopenharmony_ci
4497db96d56Sopenharmony_ci   Filter on traces of memory blocks.
4507db96d56Sopenharmony_ci
4517db96d56Sopenharmony_ci   See the :func:`fnmatch.fnmatch` function for the syntax of
4527db96d56Sopenharmony_ci   *filename_pattern*. The ``'.pyc'`` file extension is
4537db96d56Sopenharmony_ci   replaced with ``'.py'``.
4547db96d56Sopenharmony_ci
4557db96d56Sopenharmony_ci   Examples:
4567db96d56Sopenharmony_ci
4577db96d56Sopenharmony_ci   * ``Filter(True, subprocess.__file__)`` only includes traces of the
4587db96d56Sopenharmony_ci     :mod:`subprocess` module
4597db96d56Sopenharmony_ci   * ``Filter(False, tracemalloc.__file__)`` excludes traces of the
4607db96d56Sopenharmony_ci     :mod:`tracemalloc` module
4617db96d56Sopenharmony_ci   * ``Filter(False, "<unknown>")`` excludes empty tracebacks
4627db96d56Sopenharmony_ci
4637db96d56Sopenharmony_ci
4647db96d56Sopenharmony_ci   .. versionchanged:: 3.5
4657db96d56Sopenharmony_ci      The ``'.pyo'`` file extension is no longer replaced with ``'.py'``.
4667db96d56Sopenharmony_ci
4677db96d56Sopenharmony_ci   .. versionchanged:: 3.6
4687db96d56Sopenharmony_ci      Added the :attr:`domain` attribute.
4697db96d56Sopenharmony_ci
4707db96d56Sopenharmony_ci
4717db96d56Sopenharmony_ci   .. attribute:: domain
4727db96d56Sopenharmony_ci
4737db96d56Sopenharmony_ci      Address space of a memory block (``int`` or ``None``).
4747db96d56Sopenharmony_ci
4757db96d56Sopenharmony_ci      tracemalloc uses the domain ``0`` to trace memory allocations made by
4767db96d56Sopenharmony_ci      Python. C extensions can use other domains to trace other resources.
4777db96d56Sopenharmony_ci
4787db96d56Sopenharmony_ci   .. attribute:: inclusive
4797db96d56Sopenharmony_ci
4807db96d56Sopenharmony_ci      If *inclusive* is ``True`` (include), only match memory blocks allocated
4817db96d56Sopenharmony_ci      in a file with a name matching :attr:`filename_pattern` at line number
4827db96d56Sopenharmony_ci      :attr:`lineno`.
4837db96d56Sopenharmony_ci
4847db96d56Sopenharmony_ci      If *inclusive* is ``False`` (exclude), ignore memory blocks allocated in
4857db96d56Sopenharmony_ci      a file with a name matching :attr:`filename_pattern` at line number
4867db96d56Sopenharmony_ci      :attr:`lineno`.
4877db96d56Sopenharmony_ci
4887db96d56Sopenharmony_ci   .. attribute:: lineno
4897db96d56Sopenharmony_ci
4907db96d56Sopenharmony_ci      Line number (``int``) of the filter. If *lineno* is ``None``, the filter
4917db96d56Sopenharmony_ci      matches any line number.
4927db96d56Sopenharmony_ci
4937db96d56Sopenharmony_ci   .. attribute:: filename_pattern
4947db96d56Sopenharmony_ci
4957db96d56Sopenharmony_ci      Filename pattern of the filter (``str``). Read-only property.
4967db96d56Sopenharmony_ci
4977db96d56Sopenharmony_ci   .. attribute:: all_frames
4987db96d56Sopenharmony_ci
4997db96d56Sopenharmony_ci      If *all_frames* is ``True``, all frames of the traceback are checked. If
5007db96d56Sopenharmony_ci      *all_frames* is ``False``, only the most recent frame is checked.
5017db96d56Sopenharmony_ci
5027db96d56Sopenharmony_ci      This attribute has no effect if the traceback limit is ``1``.  See the
5037db96d56Sopenharmony_ci      :func:`get_traceback_limit` function and :attr:`Snapshot.traceback_limit`
5047db96d56Sopenharmony_ci      attribute.
5057db96d56Sopenharmony_ci
5067db96d56Sopenharmony_ci
5077db96d56Sopenharmony_ciFrame
5087db96d56Sopenharmony_ci^^^^^
5097db96d56Sopenharmony_ci
5107db96d56Sopenharmony_ci.. class:: Frame
5117db96d56Sopenharmony_ci
5127db96d56Sopenharmony_ci   Frame of a traceback.
5137db96d56Sopenharmony_ci
5147db96d56Sopenharmony_ci   The :class:`Traceback` class is a sequence of :class:`Frame` instances.
5157db96d56Sopenharmony_ci
5167db96d56Sopenharmony_ci   .. attribute:: filename
5177db96d56Sopenharmony_ci
5187db96d56Sopenharmony_ci      Filename (``str``).
5197db96d56Sopenharmony_ci
5207db96d56Sopenharmony_ci   .. attribute:: lineno
5217db96d56Sopenharmony_ci
5227db96d56Sopenharmony_ci      Line number (``int``).
5237db96d56Sopenharmony_ci
5247db96d56Sopenharmony_ci
5257db96d56Sopenharmony_ciSnapshot
5267db96d56Sopenharmony_ci^^^^^^^^
5277db96d56Sopenharmony_ci
5287db96d56Sopenharmony_ci.. class:: Snapshot
5297db96d56Sopenharmony_ci
5307db96d56Sopenharmony_ci   Snapshot of traces of memory blocks allocated by Python.
5317db96d56Sopenharmony_ci
5327db96d56Sopenharmony_ci   The :func:`take_snapshot` function creates a snapshot instance.
5337db96d56Sopenharmony_ci
5347db96d56Sopenharmony_ci   .. method:: compare_to(old_snapshot: Snapshot, key_type: str, cumulative: bool=False)
5357db96d56Sopenharmony_ci
5367db96d56Sopenharmony_ci      Compute the differences with an old snapshot. Get statistics as a sorted
5377db96d56Sopenharmony_ci      list of :class:`StatisticDiff` instances grouped by *key_type*.
5387db96d56Sopenharmony_ci
5397db96d56Sopenharmony_ci      See the :meth:`Snapshot.statistics` method for *key_type* and *cumulative*
5407db96d56Sopenharmony_ci      parameters.
5417db96d56Sopenharmony_ci
5427db96d56Sopenharmony_ci      The result is sorted from the biggest to the smallest by: absolute value
5437db96d56Sopenharmony_ci      of :attr:`StatisticDiff.size_diff`, :attr:`StatisticDiff.size`, absolute
5447db96d56Sopenharmony_ci      value of :attr:`StatisticDiff.count_diff`, :attr:`Statistic.count` and
5457db96d56Sopenharmony_ci      then by :attr:`StatisticDiff.traceback`.
5467db96d56Sopenharmony_ci
5477db96d56Sopenharmony_ci
5487db96d56Sopenharmony_ci   .. method:: dump(filename)
5497db96d56Sopenharmony_ci
5507db96d56Sopenharmony_ci      Write the snapshot into a file.
5517db96d56Sopenharmony_ci
5527db96d56Sopenharmony_ci      Use :meth:`load` to reload the snapshot.
5537db96d56Sopenharmony_ci
5547db96d56Sopenharmony_ci
5557db96d56Sopenharmony_ci   .. method:: filter_traces(filters)
5567db96d56Sopenharmony_ci
5577db96d56Sopenharmony_ci      Create a new :class:`Snapshot` instance with a filtered :attr:`traces`
5587db96d56Sopenharmony_ci      sequence, *filters* is a list of :class:`DomainFilter` and
5597db96d56Sopenharmony_ci      :class:`Filter` instances.  If *filters* is an empty list, return a new
5607db96d56Sopenharmony_ci      :class:`Snapshot` instance with a copy of the traces.
5617db96d56Sopenharmony_ci
5627db96d56Sopenharmony_ci      All inclusive filters are applied at once, a trace is ignored if no
5637db96d56Sopenharmony_ci      inclusive filters match it. A trace is ignored if at least one exclusive
5647db96d56Sopenharmony_ci      filter matches it.
5657db96d56Sopenharmony_ci
5667db96d56Sopenharmony_ci      .. versionchanged:: 3.6
5677db96d56Sopenharmony_ci         :class:`DomainFilter` instances are now also accepted in *filters*.
5687db96d56Sopenharmony_ci
5697db96d56Sopenharmony_ci
5707db96d56Sopenharmony_ci   .. classmethod:: load(filename)
5717db96d56Sopenharmony_ci
5727db96d56Sopenharmony_ci      Load a snapshot from a file.
5737db96d56Sopenharmony_ci
5747db96d56Sopenharmony_ci      See also :meth:`dump`.
5757db96d56Sopenharmony_ci
5767db96d56Sopenharmony_ci
5777db96d56Sopenharmony_ci   .. method:: statistics(key_type: str, cumulative: bool=False)
5787db96d56Sopenharmony_ci
5797db96d56Sopenharmony_ci      Get statistics as a sorted list of :class:`Statistic` instances grouped
5807db96d56Sopenharmony_ci      by *key_type*:
5817db96d56Sopenharmony_ci
5827db96d56Sopenharmony_ci      =====================  ========================
5837db96d56Sopenharmony_ci      key_type               description
5847db96d56Sopenharmony_ci      =====================  ========================
5857db96d56Sopenharmony_ci      ``'filename'``         filename
5867db96d56Sopenharmony_ci      ``'lineno'``           filename and line number
5877db96d56Sopenharmony_ci      ``'traceback'``        traceback
5887db96d56Sopenharmony_ci      =====================  ========================
5897db96d56Sopenharmony_ci
5907db96d56Sopenharmony_ci      If *cumulative* is ``True``, cumulate size and count of memory blocks of
5917db96d56Sopenharmony_ci      all frames of the traceback of a trace, not only the most recent frame.
5927db96d56Sopenharmony_ci      The cumulative mode can only be used with *key_type* equals to
5937db96d56Sopenharmony_ci      ``'filename'`` and ``'lineno'``.
5947db96d56Sopenharmony_ci
5957db96d56Sopenharmony_ci      The result is sorted from the biggest to the smallest by:
5967db96d56Sopenharmony_ci      :attr:`Statistic.size`, :attr:`Statistic.count` and then by
5977db96d56Sopenharmony_ci      :attr:`Statistic.traceback`.
5987db96d56Sopenharmony_ci
5997db96d56Sopenharmony_ci
6007db96d56Sopenharmony_ci   .. attribute:: traceback_limit
6017db96d56Sopenharmony_ci
6027db96d56Sopenharmony_ci      Maximum number of frames stored in the traceback of :attr:`traces`:
6037db96d56Sopenharmony_ci      result of the :func:`get_traceback_limit` when the snapshot was taken.
6047db96d56Sopenharmony_ci
6057db96d56Sopenharmony_ci   .. attribute:: traces
6067db96d56Sopenharmony_ci
6077db96d56Sopenharmony_ci      Traces of all memory blocks allocated by Python: sequence of
6087db96d56Sopenharmony_ci      :class:`Trace` instances.
6097db96d56Sopenharmony_ci
6107db96d56Sopenharmony_ci      The sequence has an undefined order. Use the :meth:`Snapshot.statistics`
6117db96d56Sopenharmony_ci      method to get a sorted list of statistics.
6127db96d56Sopenharmony_ci
6137db96d56Sopenharmony_ci
6147db96d56Sopenharmony_ciStatistic
6157db96d56Sopenharmony_ci^^^^^^^^^
6167db96d56Sopenharmony_ci
6177db96d56Sopenharmony_ci.. class:: Statistic
6187db96d56Sopenharmony_ci
6197db96d56Sopenharmony_ci   Statistic on memory allocations.
6207db96d56Sopenharmony_ci
6217db96d56Sopenharmony_ci   :func:`Snapshot.statistics` returns a list of :class:`Statistic` instances.
6227db96d56Sopenharmony_ci
6237db96d56Sopenharmony_ci   See also the :class:`StatisticDiff` class.
6247db96d56Sopenharmony_ci
6257db96d56Sopenharmony_ci   .. attribute:: count
6267db96d56Sopenharmony_ci
6277db96d56Sopenharmony_ci      Number of memory blocks (``int``).
6287db96d56Sopenharmony_ci
6297db96d56Sopenharmony_ci   .. attribute:: size
6307db96d56Sopenharmony_ci
6317db96d56Sopenharmony_ci      Total size of memory blocks in bytes (``int``).
6327db96d56Sopenharmony_ci
6337db96d56Sopenharmony_ci   .. attribute:: traceback
6347db96d56Sopenharmony_ci
6357db96d56Sopenharmony_ci      Traceback where the memory block was allocated, :class:`Traceback`
6367db96d56Sopenharmony_ci      instance.
6377db96d56Sopenharmony_ci
6387db96d56Sopenharmony_ci
6397db96d56Sopenharmony_ciStatisticDiff
6407db96d56Sopenharmony_ci^^^^^^^^^^^^^
6417db96d56Sopenharmony_ci
6427db96d56Sopenharmony_ci.. class:: StatisticDiff
6437db96d56Sopenharmony_ci
6447db96d56Sopenharmony_ci   Statistic difference on memory allocations between an old and a new
6457db96d56Sopenharmony_ci   :class:`Snapshot` instance.
6467db96d56Sopenharmony_ci
6477db96d56Sopenharmony_ci   :func:`Snapshot.compare_to` returns a list of :class:`StatisticDiff`
6487db96d56Sopenharmony_ci   instances. See also the :class:`Statistic` class.
6497db96d56Sopenharmony_ci
6507db96d56Sopenharmony_ci   .. attribute:: count
6517db96d56Sopenharmony_ci
6527db96d56Sopenharmony_ci      Number of memory blocks in the new snapshot (``int``): ``0`` if
6537db96d56Sopenharmony_ci      the memory blocks have been released in the new snapshot.
6547db96d56Sopenharmony_ci
6557db96d56Sopenharmony_ci   .. attribute:: count_diff
6567db96d56Sopenharmony_ci
6577db96d56Sopenharmony_ci      Difference of number of memory blocks between the old and the new
6587db96d56Sopenharmony_ci      snapshots (``int``): ``0`` if the memory blocks have been allocated in
6597db96d56Sopenharmony_ci      the new snapshot.
6607db96d56Sopenharmony_ci
6617db96d56Sopenharmony_ci   .. attribute:: size
6627db96d56Sopenharmony_ci
6637db96d56Sopenharmony_ci      Total size of memory blocks in bytes in the new snapshot (``int``):
6647db96d56Sopenharmony_ci      ``0`` if the memory blocks have been released in the new snapshot.
6657db96d56Sopenharmony_ci
6667db96d56Sopenharmony_ci   .. attribute:: size_diff
6677db96d56Sopenharmony_ci
6687db96d56Sopenharmony_ci      Difference of total size of memory blocks in bytes between the old and
6697db96d56Sopenharmony_ci      the new snapshots (``int``): ``0`` if the memory blocks have been
6707db96d56Sopenharmony_ci      allocated in the new snapshot.
6717db96d56Sopenharmony_ci
6727db96d56Sopenharmony_ci   .. attribute:: traceback
6737db96d56Sopenharmony_ci
6747db96d56Sopenharmony_ci      Traceback where the memory blocks were allocated, :class:`Traceback`
6757db96d56Sopenharmony_ci      instance.
6767db96d56Sopenharmony_ci
6777db96d56Sopenharmony_ci
6787db96d56Sopenharmony_ciTrace
6797db96d56Sopenharmony_ci^^^^^
6807db96d56Sopenharmony_ci
6817db96d56Sopenharmony_ci.. class:: Trace
6827db96d56Sopenharmony_ci
6837db96d56Sopenharmony_ci   Trace of a memory block.
6847db96d56Sopenharmony_ci
6857db96d56Sopenharmony_ci   The :attr:`Snapshot.traces` attribute is a sequence of :class:`Trace`
6867db96d56Sopenharmony_ci   instances.
6877db96d56Sopenharmony_ci
6887db96d56Sopenharmony_ci   .. versionchanged:: 3.6
6897db96d56Sopenharmony_ci      Added the :attr:`domain` attribute.
6907db96d56Sopenharmony_ci
6917db96d56Sopenharmony_ci   .. attribute:: domain
6927db96d56Sopenharmony_ci
6937db96d56Sopenharmony_ci      Address space of a memory block (``int``). Read-only property.
6947db96d56Sopenharmony_ci
6957db96d56Sopenharmony_ci      tracemalloc uses the domain ``0`` to trace memory allocations made by
6967db96d56Sopenharmony_ci      Python. C extensions can use other domains to trace other resources.
6977db96d56Sopenharmony_ci
6987db96d56Sopenharmony_ci   .. attribute:: size
6997db96d56Sopenharmony_ci
7007db96d56Sopenharmony_ci      Size of the memory block in bytes (``int``).
7017db96d56Sopenharmony_ci
7027db96d56Sopenharmony_ci   .. attribute:: traceback
7037db96d56Sopenharmony_ci
7047db96d56Sopenharmony_ci      Traceback where the memory block was allocated, :class:`Traceback`
7057db96d56Sopenharmony_ci      instance.
7067db96d56Sopenharmony_ci
7077db96d56Sopenharmony_ci
7087db96d56Sopenharmony_ciTraceback
7097db96d56Sopenharmony_ci^^^^^^^^^
7107db96d56Sopenharmony_ci
7117db96d56Sopenharmony_ci.. class:: Traceback
7127db96d56Sopenharmony_ci
7137db96d56Sopenharmony_ci   Sequence of :class:`Frame` instances sorted from the oldest frame to the
7147db96d56Sopenharmony_ci   most recent frame.
7157db96d56Sopenharmony_ci
7167db96d56Sopenharmony_ci   A traceback contains at least ``1`` frame. If the ``tracemalloc`` module
7177db96d56Sopenharmony_ci   failed to get a frame, the filename ``"<unknown>"`` at line number ``0`` is
7187db96d56Sopenharmony_ci   used.
7197db96d56Sopenharmony_ci
7207db96d56Sopenharmony_ci   When a snapshot is taken, tracebacks of traces are limited to
7217db96d56Sopenharmony_ci   :func:`get_traceback_limit` frames. See the :func:`take_snapshot` function.
7227db96d56Sopenharmony_ci   The original number of frames of the traceback is stored in the
7237db96d56Sopenharmony_ci   :attr:`Traceback.total_nframe` attribute. That allows to know if a traceback
7247db96d56Sopenharmony_ci   has been truncated by the traceback limit.
7257db96d56Sopenharmony_ci
7267db96d56Sopenharmony_ci   The :attr:`Trace.traceback` attribute is an instance of :class:`Traceback`
7277db96d56Sopenharmony_ci   instance.
7287db96d56Sopenharmony_ci
7297db96d56Sopenharmony_ci   .. versionchanged:: 3.7
7307db96d56Sopenharmony_ci      Frames are now sorted from the oldest to the most recent, instead of most recent to oldest.
7317db96d56Sopenharmony_ci
7327db96d56Sopenharmony_ci   .. attribute:: total_nframe
7337db96d56Sopenharmony_ci
7347db96d56Sopenharmony_ci      Total number of frames that composed the traceback before truncation.
7357db96d56Sopenharmony_ci      This attribute can be set to ``None`` if the information is not
7367db96d56Sopenharmony_ci      available.
7377db96d56Sopenharmony_ci
7387db96d56Sopenharmony_ci   .. versionchanged:: 3.9
7397db96d56Sopenharmony_ci      The :attr:`Traceback.total_nframe` attribute was added.
7407db96d56Sopenharmony_ci
7417db96d56Sopenharmony_ci   .. method:: format(limit=None, most_recent_first=False)
7427db96d56Sopenharmony_ci
7437db96d56Sopenharmony_ci      Format the traceback as a list of lines. Use the :mod:`linecache` module to
7447db96d56Sopenharmony_ci      retrieve lines from the source code. If *limit* is set, format the *limit*
7457db96d56Sopenharmony_ci      most recent frames if *limit* is positive. Otherwise, format the
7467db96d56Sopenharmony_ci      ``abs(limit)`` oldest frames. If *most_recent_first* is ``True``, the order
7477db96d56Sopenharmony_ci      of the formatted frames is reversed, returning the most recent frame first
7487db96d56Sopenharmony_ci      instead of last.
7497db96d56Sopenharmony_ci
7507db96d56Sopenharmony_ci      Similar to the :func:`traceback.format_tb` function, except that
7517db96d56Sopenharmony_ci      :meth:`.format` does not include newlines.
7527db96d56Sopenharmony_ci
7537db96d56Sopenharmony_ci      Example::
7547db96d56Sopenharmony_ci
7557db96d56Sopenharmony_ci          print("Traceback (most recent call first):")
7567db96d56Sopenharmony_ci          for line in traceback:
7577db96d56Sopenharmony_ci              print(line)
7587db96d56Sopenharmony_ci
7597db96d56Sopenharmony_ci      Output::
7607db96d56Sopenharmony_ci
7617db96d56Sopenharmony_ci          Traceback (most recent call first):
7627db96d56Sopenharmony_ci            File "test.py", line 9
7637db96d56Sopenharmony_ci              obj = Object()
7647db96d56Sopenharmony_ci            File "test.py", line 12
7657db96d56Sopenharmony_ci              tb = tracemalloc.get_object_traceback(f())
766