Observation and diagnostics · Intermediate

Heap profiles: inspect origins of retained memory

Use Python tracemalloc to distinguish retained traced memory, peak usage, process RSS, allocation origins, and retention causes.

Ask Logeia about this articleTry the three questionsReview your answers

Updated

On this page
  1. Define the measured memory domain
  2. Start tracing before the relevant allocations
  3. Compare two snapshots
  4. Separate current usage from the peak
  5. Begin with a bounded retention example
  6. Bound overhead and inspect exported data
  7. Ask Logeia about this articleCheck your understanding

Define the measured memory domain

Before reading a heap profile, determine whether it describes currently retained objects or cumulative allocations. Python tracemalloc tracks memory blocks allocated through traced Python mechanisms and associates them with allocation locations. Its totals are not the same quantity as process RSS reported by the operating system. Native extensions and allocator-retained capacity can fall across different accounting boundaries. An RSS increase therefore does not automatically establish growth in live traced Python objects. Identify the measured domain first. Otherwise two correct tools can appear contradictory simply because they describe different layers of memory rather than disagreeing about one shared number.

Start tracing before the relevant allocations

Start tracemalloc before the allocations relevant to the investigation, either through initialization or a startup option. Do not assume it can reconstruct every allocation that occurred before tracing began. Traceback depth trades diagnostic information against collection cost. A single recorded line can make different callers of a common helper look identical. Also define whether startup imports and warm-up belong to the measured workload. Use the same tracing configuration for before-and-after snapshots and document what the baseline includes. Reproducible scope is necessary before interpreting a difference as growth caused by one business operation.

Compare two snapshots

Take a baseline snapshot, execute a bounded number of equivalent operations, and take another snapshot. Compare them by line or traceback to inspect growth and reduction. A growing allocation location identifies where retained traced blocks originated, not necessarily the code responsible for keeping them alive. A cache, global reference, queue, or reference cycle may retain objects allocated elsewhere. Separate allocation origin from retention cause. Follow the lifecycle and ownership of the relevant objects rather than deleting the line with the largest total simply because it appears prominently in the profile. The snapshot comparison provides a lead, not a complete causal explanation.

Separate current usage from the peak

get_traced_memory returns current traced usage and the peak observed during tracing. After a large temporary list is released, current usage can fall while the recorded peak remains high. A large peak alone is not proof of a leak. Conversely, current usage that repeatedly fails to return can suggest unbounded retention, but intentional cache filling is another explanation. Repeat equivalent workloads and inspect whether growth stabilizes at a defined bound. A slope in one short graph does not prove unlimited long-term growth. If the peak is reset, record the interval to which the new peak applies.

Begin with a bounded retention example

Use a bounded example that retains bytearrays in a list, inspects traced usage, drops the references, and inspects usage again. Do not expect process RSS to decline by exactly the same amount at the same moment; the allocator can retain capacity. Exact byte totals depend on Python version and surrounding allocations. Report observations tied to the operations, such as increased traced retention or a peak remaining above current usage after release. A small local example validates understanding of the tool’s accounting before the investigation expands to a complex service. Its output is not automatically a prediction of production memory behavior.

Python 3.12
import gc, tracemalloc
tracemalloc.start(5)
before = tracemalloc.take_snapshot()
items = [bytearray(4096) for _ in range(64)]
held, peak = tracemalloc.get_traced_memory()
assert held > 0 and peak >= held
print('top retained differences', tracemalloc.take_snapshot().compare_to(before, 'lineno')[:3])
del items
gc.collect()
current, final_peak = tracemalloc.get_traced_memory()
print({'held_bytes': held, 'current_bytes': current, 'peak_bytes': final_peak})
assert final_peak >= current
tracemalloc.stop()

Bound overhead and inspect exported data

Snapshots and deeper tracebacks consume time and memory. Measure their impact in a bounded interval before enabling expensive tracing continuously in production. Exported paths can reveal internal structure, so inspect sharing scope and report contents. Stopping tracing can discard information needed for a comparison; complete the intended observations before cleanup. Remedies should follow the identified cause, such as bounded retention, clearer ownership, or fewer copies. Repeated garbage collection is not a universal cure for every rising memory chart. The diagnostic goal is a defensible lifecycle explanation, not merely forcing one counter downward temporarily.

Reading and practice are recorded separately in this browser, for each language.

Learn this in order

Build your CS foundations · STEP 12

Choose a learning path