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(file_name=None, destination=None, *, bool native_traces=False, unsigned int memory_interval_ms=10, bool follow_fork=False, bool trace_python_allocators=False)#

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.

  • native_traces (bool) -- Whether or not to capture native stack frames, in addition to Python stack frames (see Native tracking). 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.

class memray.FileDestination(path: Union[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.