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 thewith
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 thewith
block ends, you will need to create a freshTracker
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[pathlib.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 theTracker
constructor, the process will immediately create a server socket on the given port and wait for a reader to connect (see Live tracking). TheTracker
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.