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