Add Python object reference tracking

[pablogsal]

This feature adds the capability to track Python objects throughout their lifecycle in memray. The implementation introduces a reference tracking system that records PyObject creation and destruction events, storing them as TrackedObject records in the memray capture file with associated stack traces. The Tracker class now accepts a reference_tracking flag to enable this functionality and provides a get_surviving_objects() method to retrieve live objects at the end of tracking.

Object tracking works across threads and supports native, Python, and hybrid stack traces, providing insights into Python object lifetimes. This enhancement extends memray beyond memory allocation tracking to give developers a powerful tool for understanding object lifecycles and identifying potential reference leaks.

With this addition, memray can now correlate memory allocations with the Python objects that trigger them, enabling more precise debugging of memory usage patterns. The feature is particularly useful for identifying objects that persist longer than expected or detecting unexpected object creation patterns. By tracking both memory allocations and object references, memray provides a more complete picture of a program's memory behavior, helping developers optimize memory usage and resolve leaks more effectively.

This implementation leverages the new Python reference tracing API that was introduced in CPython 3.13.

Signed-off-by: Pablo Galindo [email protected]

Issue number of the reported bug or feature request: #

Describe your changes A clear and concise description of the changes you have made.

Testing performed Describe the testing you have performed to ensure that the bug has been addressed, or that the new feature works as planned.

Additional context Add any other context about your contribution here.

[codecov-commenter]

Codecov Report

:x: Patch coverage is 90.32258% with 42 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 92.39%. Comparing base (87ff508) to head (a4c03e6).

Files with missing lines	Patch %	Lines
tests/integration/test_object_tracking.py	91.47%	19 Missing :warning:
src/memray/_memray/tracking_api.cpp	78.57%	9 Missing :warning:
src/memray/_memray/record_reader.cpp	90.90%	6 Missing :warning:
src/memray/_memray/record_writer.cpp	83.33%	5 Missing :warning:
src/memray/_memray/socket_reader_thread.cpp	0.00%	3 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #752      +/-   ##
==========================================
+ Coverage   91.19%   92.39%   +1.19%     
==========================================
  Files          96       99       +3     
  Lines       12071    11814     -257     
  Branches      415      423       +8     
==========================================
- Hits        11008    10915      -93     
+ Misses       1063      899     -164     

Flag	Coverage Δ
cpp	92.39% <90.32%> (+1.19%)	:arrow_up:
python_and_cython	92.39% <90.32%> (+1.19%)	:arrow_up:

Flags with carried forward coverage won't be shown. Click here to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• :package: JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pablogsal]

Tests require 3.13.3 at least because before there is a bug that causes some objects to be identified wrongly. cibuildwheel only has this when https://github.com/pypa/cibuildwheel/pull/2359 passes

[joerick]

I just released cibuildwheel with 3.13.3 support!