repository·main·Indexed 12 days ago
https://github.com/bloomberg/memrayA high-performance memory profiler for Python that tracks allocations in Python code, native C/C++ extensions, and the Python interpreter. It provides tools for finding memory leaks and allocation hotspots via flame graphs, live monitoring, and a pytest-memray plugin.
Memray is a memory profiler that tracks memory allocations in Python code, native extension modules, and the Python interpreter itself. It can be used as a CLI tool or as a library for fine-grained profiling.
Typical Workflow:
memray run subcommand to execute your program and create a capture file.memray flamegraph) to analyze the captured data file.Memray is a memory profiler for Python designed to track memory allocations across three layers: Python code, native extension modules (C/C++), and the Python interpreter itself.
It is useful for:
Key capabilities include:
Note: Memray only works on Linux and MacOS.
By default, Memray groups allocations occurring at the same source location across different threads together in the flame graph.
If you use the --split-threads option, Memray enables thread-specific filtering. In the generated HTML report, a "Filter Thread" dropdown will appear, allowing you to select a specific thread to view its individual allocation pattern. To return to the merged view, use the "Reset" entry in the dropdown. Note that the root node (<root>) is always displayed as thread 0.
memray flamegraph --split-threads <results>Memray flame graph reports consist of three main sections:
How to read the graph:
When viewing the default icicle graph, use these rules to find memory issues:
Memray has specific limitations regarding process execution and certain extensions:
exec call. If a tracked child process calls an os.exec function (even to start a new Python interpreter), allocations in the new process will not be reported.multiprocessing start method is spawn, which uses exec and will therefore not be tracked.profiling support. To see inside Cython modules, you must use native tracking.greenlet library. Using the Memray API to start tracking in one thread while another thread is using greenlet may result in incorrect stacks.The threshold determines the sensitivity of the 'temporary' classification:
Standard flame graphs show the call hierarchy (children are functions called by the parent). In this view, if a function is called from multiple locations, it appears as multiple leaf nodes.
Inverted flame graphs (generated with --inverted) reverse this: children are the functions that called the node. This aggregates all calls to a specific function into a single block, making it much easier to see the total memory spent in a specific function across the entire program execution.
memray flamegraph --inverted <results>Memory fragmentation occurs when the system allocator's free memory is spread across the address space in small, non-contiguous fragments. This can cause the resident memory size to increase in unpredictable ways because the allocator might request more memory from the OS even if the total amount of free memory is sufficient to satisfy a new request.
Because fragmentation depends on the specific system allocator (like GLIBC), a memory profiler cannot directly tell you why resident memory is growing due to fragmentation; it can only show that the resident size is increasing.
Memray's performance impact varies depending on the tracing options used. The following configurations represent the main modes of operation:
--trace-python-allocators: Tracks allocations made via Python allocators. This provides more granular detail but incurs significantly higher overhead due to the high frequency of small object allocations in Python.--native: Enables native (C/C++) stack trace tracking. This adds overhead related to capturing the native call stack.--native --trace-python-allocators: Combines both native tracking and Python allocator tracking, representing the highest overhead configuration.Using @functools.cache (which is equivalent to @functools.lru_cache(maxsize=None)) on an instance method can cause unexpected memory leaks.
Because the cache stores the arguments used to call the function, and the first argument of an instance method is self, the cache retains a reference to the class instance (self) indefinitely. This prevents the Python Garbage Collector from deallocating the instance, even if it is no longer used elsewhere in your program.
To resolve this, you can:
self.my_cache = functools.cache(self._uncached_func)) so the cache is released when the instance is destroyed.@functools.lru_cache(maxsize=N) instead of @cache to ensure old entries are evicted..cache_clear() on the decorated function.# Example of limiting cache size to prevent unbounded growth
@functools.lru_cache(maxsize=10000)
def factorial_plus(self, n: int) -> int:
return n * self.factorial_plus(n - 1) + self.inc if n else 1 + self.inc