Finding a memory leak with tracemalloc snapshots

Goal

Attribute growing memory in a long-running Python process to the source lines that allocate it, using only the standard library.

Prerequisites

A reproduction (a loop, request sequence or job after which resident memory is higher than before), the ability to restart the process with an environment variable or flag, and Python 3.

Steps

1. Start tracing before the suspect code runs: PYTHONTRACEMALLOC=25, -X tracemalloc=25, or tracemalloc.start(25) as early as possible. The number is the traceback depth stored per allocation; the documentation states the default is one frame, which only names the allocating line, and that more frames are needed to group statistics by full traceback.
2. Warm up: run the operation a few times so imports, caches and connection pools reach a steady state, then take s1 = tracemalloc.take_snapshot().
3. Run the operation a known number of times, for example 100, and take s2.
4. Filter noise as in the documentation's example: s.filter_traces((tracemalloc.Filter(False, "<frozen importlib._bootstrap>"), tracemalloc.Filter(False, "<unknown>"))).
5. Compare: for stat in s2.compare_to(s1, "lineno")[:10]: print(stat). Entries are sorted by absolute size difference; a leak shows as a line whose size_diff and count_diff scale with the iteration count. Re-run with key "traceback" and print stat.traceback.format() to see who reached that line.
6. Confirm with a different iteration count: a leak grows proportionally, a cache plateaus.
7. For peaks rather than growth, wrap the block with get_traced_memory() (current and peak) and reset_peak(), as the documentation's example does.
8. Persist with snapshot.dump(path) so someone else can Snapshot.load(path) and inspect without reproducing.

Expected result

A short list of source lines with per-iteration growth and the call path reaching them; the usual culprits are a list or dict appended to and never trimmed, an unbounded cache, objects kept by a closure or by lru_cache on a method, and handlers registered repeatedly.

Limits and test basis

tracemalloc sees allocations made through Python's allocators; memory that C libraries allocate directly and heap fragmentation are invisible, so resident size can grow while traced size does not. Tracing costs memory and CPU that rise with the frame depth (the documentation offers get_tracemalloc_memory() to measure it), so use it in a reproduction rather than permanently in production. The procedure follows the cited documentation; no measurement is claimed.