Memray API

Memray exposes an API that can be used to programmatically activate or deactivate tracking of a Python process’s memory allocations. You do this by creating a Tracker object and using it as a context manager in a with statement. While the body of the with statement runs, tracking will be enabled, with output being sent to a destination you specify when creating the Tracker. When the with block ends, tracking will be disabled and the output will be flushed and closed.

API Usage

class memray.Tracker

Context manager for tracking memory allocations in a Python script.

You can track memory allocations in a Python process by using a Tracker as a context manager:

with memray.Tracker("some_output_file.bin"):

Any code inside of the with block will have its allocations tracked. Any allocations made by other threads will also be tracked for the duration of the with block. Because of the way tracking works, there can only be one tracker active in the entire program at a time. Attempting to activate a tracker while one is already active will raise an exception, as will attempting to activate the same tracker more than once. If you want to re-enable tracking after the with block ends, you will need to create a fresh Tracker instance.

Parameters:

  • file_name (str or pathlib.Path) -- The name of the file to write the captured allocations into. This is the only argument that can be passed positionally. If not provided, the destination keyword argument must be provided.

  • destination (FileDestination or SocketDestination) -- The destination to write captured allocations to. If provided, the file_name argument must not be provided.

  • native_traces (bool) -- Whether or not to capture native stack frames, in addition to Python stack frames (see Native tracking). Defaults to False.

  • trace_python_allocators (bool) -- Whether or not to trace Python allocators as independent allocations. (see Python allocators). Defaults to False.

  • follow_fork (bool) -- Whether or not to continue tracking in a subprocess that is forked from the tracked process (see Tracking across forks). Defaults to False.

  • memory_interval_ms (int) -- How many milliseconds to wait between sending periodic resident set size updates. By default, every 10 milliseconds a record is written that contains the current timestamp and the total number of bytes of virtual memory allocated by the process. These records are used to create the graph of memory usage over time that appears at the top of the flame graph, for instance. This parameter lets you adjust the frequency between updates, though you shouldn’t need to change it.

  • file_format (FileFormat) -- The format that should be used when writing to the capture file. See the FileFormat documentation for a list of supported file formats and their limitations.

class memray.FileDestination(path: Path | str, overwrite: bool = False, compress_on_exit: bool = True)[source]

Specify an output file to write captured allocations into.

Parameters:

  • path -- The path to the output file.

  • overwrite -- By default, if a file already exists at that path an exception will be raised. If you provide overwrite=True, then the existing file will be overwritten instead.

class memray.SocketDestination(server_port: int, address: str = '127.0.0.1')[source]

Specify a port to serve captured allocations on.

When a SocketDestination is passed to the Tracker constructor, the process will immediately create a server socket on the given port and wait for a reader to connect (see Live tracking). The Tracker constructor will not return until a client has connected. Any records the tracker goes on to capture will be written over the socket to the attached client.

Parameters:

  • server_port -- The port to accept a client connection on.

  • address -- The address to bind the server socket to. This should generally be left alone, but you might want to use "0.0.0.0" to accept connections from clients on other machines. Note that sending records to clients on other machines is generally a bad idea, though. In particular, this won’t play nicely with Native tracking, because the client on the remote machine won’t have access to the shared libraries used by the tracked process.

class memray.FileFormat

This enumeration lists the capture file formats that Memray can write. The Tracker constructor accepts a file_format keyword argument for choosing a different format than the default.

ALL_ALLOCATIONS

Record every allocation that the tracked process performs. This is the default format. The produced capture files may be very large if the process performs many allocations. This is the only format that allows detecting temporary allocations or using the stats reporter.

AGGREGATED_ALLOCATIONS

For every location where the tracked process performed any allocations, the capture file includes a count of:

  • How many allocations at that location had not yet been deallocated when the process reached its heap memory high water mark

  • How many bytes had been allocated at that location and not yet deallocated when the process reached its heap memory high water mark

  • How many allocations at that location were leaked (i.e. not deallocated before tracking stopped)

  • How many bytes were leaked by allocations at that location

You cannot find temporary allocations using this capture file format, since finding temporary allocations requires knowing when each allocation was deallocated, and that information is lost by the aggregation. You also cannot use the stats reporter with this capture file format, because it needs to see every allocation’s size to compute its statistics.

Additionally, if the process is killed before tracking ends (for instance, by the Linux OOM killer), then no useful information is ever written to the capture file, because aggregation was still happening inside the process when it died.

If you can live with these limitations, then AGGREGATED_ALLOCATIONS results in much smaller capture files that can be used seamlessly with most reporters.