Generated man page for Memray

memray.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MEMRAY" "1" "Jan 12, 2024" "" "memray"
.SH NAME
memray \- Python memory profiler
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
memray [\-h] [\-v] [\-V]
       {run,flamegraph,table,live,tree,parse,summary,stats,transform,attach,detach}
       ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
Memray is a memory profiler for Python applications.
.sp
Memray can track memory allocations in Python code, in native extension modules, and in the Python
interpreter itself. It can generate several different types of reports to help you analyze the captured
memory usage data. While commonly used as a CLI tool, it can also be used as a library to perform more
fine\-grained profiling tasks.
.sp
Most commonly you will use the \fBmemray run\fP subcommand to create a capture file, and then use a reporter
like the \fBmemray flamegraph\fP subcommand to analyze it.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
This manual page only documents usage of the Memray subcommands that can be invoked from the command line.
See \fI\%https://bloomberg.github.io/memray/overview.html\fP for the full Memray documentation, which
includes advice for interpreting Memray reports, example programs, API documentation, information about
integrating Memray into Jupyter notebooks and pytest test suites, explanations to help you understand how
Python uses memory and how Memray gathers information about memory usage, and more.
.UNINDENT
.UNINDENT
.sp
Please submit feedback, ideas, and bug reports by filing a new issue at
https://github.com/bloomberg/memray/issues

.SH RUN SUB-COMMAND
.sp
Run the specified application and track memory usage

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray run [\-m module | \-c cmd | file] [args]
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-o, \-\-output
Output file name (default: <process_name>.<pid>.bin)
.TP
.B \-\-live
Start a live tracking session and immediately connect a live server
.TP
.B \-\-live\-remote
Start a live tracking session and wait until a client connects
.TP
.B \-\-live\-port, \-p
Port to use when starting live tracking (default: random free port)
.TP
.B \-\-aggregate
Write aggregated stats to the output file instead of all allocations
.TP
.B \-\-native
Track native (C/C++) stack frames as well
.TP
.B \-\-follow\-fork
Record allocations in child processes forked from the tracked script
.TP
.B \-\-trace\-python\-allocators
Record allocations made by the pymalloc allocator
.TP
.B \-q, \-\-quiet
Don\(aqt show any tracking\-specific output while running
.TP
.B \-f, \-\-force
If the output file already exists, overwrite it
.TP
.B \-\-compress\-on\-exit
Compress the resulting file using lz4 after tracking completes
.TP
.B \-\-no\-compress
Do not compress the resulting file using lz4
.TP
.B \-c
Program passed in as string
.TP
.B \-m
Run library module as a script (terminates option list)
.UNINDENT
.SH FLAMEGRAPH SUB-COMMAND
.sp
Generate an HTML flame graph for peak memory usage

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray flamegraph [\-h] [\-o OUTPUT] [\-f] [\-\-temporal]
                         [\-\-leaks | \-\-temporary\-allocation\-threshold N | \-\-temporary\-allocations]
                         [\-\-split\-threads] [\-\-inverted]
                         [\-\-max\-memory\-records MAX_MEMORY_RECORDS]
                         results
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B results
Results of the tracker run
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-o, \-\-output
Output file name
.TP
.B \-f, \-\-force
If the output file already exists, overwrite it
.TP
.B \-\-temporal
Generate a dynamic flame graph that can analyze allocations in a user\-selected time range.
.TP
.B \-\-leaks
Show memory leaks, instead of peak memory usage
.TP
.B \-\-temporary\-allocation\-threshold
Report temporary allocations, as opposed to leaked allocations
or high watermark allocations.  An allocation is considered
temporary if at most N other allocations occur before it is
deallocated.  With N=0, an allocation is temporary only if it
is immediately deallocated before any other allocation occurs.
.sp
Default: \-1
.TP
.B \-\-temporary\-allocations
Equivalent to \-\-temporary\-allocation\-threshold=1
.TP
.B \-\-split\-threads
Do not merge allocations across threads
.TP
.B \-\-inverted
Invert flame graph
.TP
.B \-\-max\-memory\-records
Maximum number of memory records to display
.UNINDENT
.SH TABLE SUB-COMMAND
.sp
Generate an HTML table with all records in the peak memory usage

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray table [\-h] [\-o OUTPUT] [\-f]
                    [\-\-leaks | \-\-temporary\-allocation\-threshold N | \-\-temporary\-allocations]
                    results
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B results
Results of the tracker run
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-o, \-\-output
Output file name
.TP
.B \-f, \-\-force
If the output file already exists, overwrite it
.TP
.B \-\-leaks
Show memory leaks, instead of peak memory usage
.TP
.B \-\-temporary\-allocation\-threshold
Report temporary allocations, as opposed to leaked allocations
or high watermark allocations.  An allocation is considered
temporary if at most N other allocations occur before it is
deallocated.  With N=0, an allocation is temporary only if it
is immediately deallocated before any other allocation occurs.
.sp
Default: \-1
.TP
.B \-\-temporary\-allocations
Equivalent to \-\-temporary\-allocation\-threshold=1
.UNINDENT
.SH LIVE SUB-COMMAND
.sp
Remotely monitor allocations in a text\-based interface

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray live [\-h] port
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B port
Remote port to connect to
.UNINDENT
.SH TREE SUB-COMMAND
.sp
Generate a tree view in the terminal for peak memory usage

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray tree [\-h] [\-b BIGGEST_ALLOCS]
                   [\-\-temporary\-allocation\-threshold N | \-\-temporary\-allocations]
                   results
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B results
Results of the tracker run
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-b, \-\-biggest\-allocs
Show n biggest allocations (defaults to 200)
.sp
Default: 200
.TP
.B \-\-temporary\-allocation\-threshold
Report temporary allocations, as opposed to leaked allocations
or high watermark allocations.  An allocation is considered
temporary if at most N other allocations occur before it is
deallocated.  With N=0, an allocation is temporary only if it
is immediately deallocated before any other allocation occurs.
.sp
Default: \-1
.TP
.B \-\-temporary\-allocations
Equivalent to \-\-temporary\-allocation\-threshold=1
.UNINDENT
.SH PARSE SUB-COMMAND
.sp
Debug a results file by parsing and printing each record in it

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray parse [\-h] results
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B results
Results of the tracker run
.UNINDENT
.SH SUMMARY SUB-COMMAND
.sp
Generate a terminal\-based summary report of the functions that allocate most memory

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray summary [\-h] [\-s SORT_COLUMN] [\-r MAX_ROWS]
                      [\-\-temporary\-allocation\-threshold N | \-\-temporary\-allocations]
                      results
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B results
Results of the tracker run
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-s, \-\-sort\-column
Column number to sort on
.sp
Default: 1
.TP
.B \-r, \-\-max\-rows
Maximum number of rows to display
.TP
.B \-\-temporary\-allocation\-threshold
Report temporary allocations, as opposed to leaked allocations
or high watermark allocations.  An allocation is considered
temporary if at most N other allocations occur before it is
deallocated.  With N=0, an allocation is temporary only if it
is immediately deallocated before any other allocation occurs.
.sp
Default: \-1
.TP
.B \-\-temporary\-allocations
Equivalent to \-\-temporary\-allocation\-threshold=1
.UNINDENT
.SH STATS SUB-COMMAND
.sp
Generate high level stats of the memory usage in the terminal

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray stats [\-h] [\-n NUM_LARGEST] [\-\-json] [\-o OUTPUT] [\-f] results
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B results
Results of the tracker run
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-n, \-\-num\-largest
Displays the top \(aqn\(aq largest allocating functions. Default is 5
.sp
Default: 5
.TP
.B \-\-json
Exports stats to a JSON file
.TP
.B \-o, \-\-output
Output file name for JSON output
.TP
.B \-f, \-\-force
If the JSON output file already exists, overwrite it
.UNINDENT
.SH TRANSFORM SUB-COMMAND
.sp
Generate reports files in different formats

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray transform [\-h] [\-o OUTPUT] [\-f]
                        [\-\-leaks | \-\-temporary\-allocation\-threshold N | \-\-temporary\-allocations]
                        format results
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B format
Format to use for the report. Available formats: gprof2dot, csv
.TP
.B results
Results of the tracker run
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-o, \-\-output
Output file name
.TP
.B \-f, \-\-force
If the output file already exists, overwrite it
.TP
.B \-\-leaks
Show memory leaks, instead of peak memory usage
.TP
.B \-\-temporary\-allocation\-threshold
Report temporary allocations, as opposed to leaked allocations
or high watermark allocations.  An allocation is considered
temporary if at most N other allocations occur before it is
deallocated.  With N=0, an allocation is temporary only if it
is immediately deallocated before any other allocation occurs.
.sp
Default: \-1
.TP
.B \-\-temporary\-allocations
Equivalent to \-\-temporary\-allocation\-threshold=1
.UNINDENT
.SH ATTACH SUB-COMMAND
.sp
Begin tracking allocations in an already\-started process

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray attach [\-h] [\-o FILE] [\-f] [\-\-aggregate] [\-\-native] [\-\-follow\-fork]
                     [\-\-trace\-python\-allocators] [\-\-compress\-on\-exit | \-\-no\-compress]
                     [\-\-duration DURATION] [\-\-method {auto,gdb,lldb}] [\-v]
                     pid
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B pid
Process id to affect
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-o, \-\-output
Capture allocations into the given file instead of starting a live tracking session
.TP
.B \-f, \-\-force
If the output file already exists, overwrite it
.TP
.B \-\-aggregate
Write aggregated stats to the output file instead of all allocations
.TP
.B \-\-native
Track native (C/C++) stack frames as well
.TP
.B \-\-follow\-fork
Record allocations in child processes forked from the tracked script
.TP
.B \-\-trace\-python\-allocators
Record allocations made by the pymalloc allocator
.TP
.B \-\-compress\-on\-exit
Compress the resulting file using lz4 after tracking completes
.TP
.B \-\-no\-compress
Do not compress the resulting file using lz4
.TP
.B \-\-duration
Duration to track for (in seconds)
.TP
.B \-\-method
Possible choices: auto, gdb, lldb
.sp
Method to use for injecting commands into the remote process
.sp
Default: \(dqauto\(dq
.TP
.B \-v, \-\-verbose
Print verbose debugging information.
.UNINDENT
.SH DETACH SUB-COMMAND
.sp
End the tracking started by a previous \fBmemray attach\fP call

.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: memray detach [\-h] [\-\-method {auto,gdb,lldb}] [\-v] pid
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Positional Arguments
.INDENT 0.0
.TP
.B pid
Process id to affect
.UNINDENT
.SS Named Arguments
.INDENT 0.0
.TP
.B \-\-method
Possible choices: auto, gdb, lldb
.sp
Method to use for injecting commands into the remote process
.sp
Default: \(dqauto\(dq
.TP
.B \-v, \-\-verbose
Print verbose debugging information.
.UNINDENT
.\" Generated by docutils manpage writer.
.