A memory profiler for Linux
- Can be used to analyze memory leaks, see where exactly the memory is being consumed, identify temporary allocations and investigate excessive memory fragmentation
- Gathers every allocation and deallocation, along with full stack traces
- Uses a custom, tailor-made stack unwinding implementation which makes it a lot cheaper than other similar tools, potentially up to orders of magnitude faster in some cases
- Can export the data it gathered into various different formats; it can export the data as JSON (so you can analyze it yourself if you want), as Heaptrack (so you can use the excellent Heaptrack GUI for analysis) and as a flamegraph
- Has its own Web-based GUI which can be used for analysis
- Can dynamically stream the profiling data to another machine instead of saving it locally, which is useful for profiling on memory-constrained systems
- Supports AMD64, ARM, AArch64 and MIPS64 architectures (where MIPS64 requires a tiny out-of-tree kernel patch for
Install Rust nightly and the Yarn package manager (for building the GUI)
$ cargo build --release -p memory-profiler $ cargo build --release -p memory-profiler-cli
Grab the binaries from
$ LD_PRELOAD=./libmemory_profiler.so ./your_application $ ./memory-profiler-cli server memory-profiling_*.dat
Then open your Web browser and point it at
http://localhost:8080 to access the GUI.
If you'd rather not use the GUI you can also make use of the REST API exposed by the server. For example:
Generate a flamegraph of leaked allocations:
$ curl "http://localhost:8080/data/last/export/flamegraph?lifetime=only_leaked" > flame.svg
Export the leaked allocations as an ASCII tree:
$ curl "http://localhost:8080/data/last/allocation_ascii_tree?lifetime=only_leaked"
Export the biggest three allocations made by the application to JSON: (You should pipe the output to
json_reformatfor human readable output.)
$ curl "http://localhost:8080/data/last/allocations?sort_by=size&order=dsc&count=3"
Export the biggest three call sites with at least 10 allocations where at least 50% are leaked:
$ curl "http://localhost:8080/data/last/allocation_groups?group_allocations_min=10&group_leaked_allocations_min=50%&sort_by=all.size&count=3"
REST API exposed by
A list of loaded data files:
JSON containing a list of matched allocations:
JSON whose each entry corresponds to a group of matched allocations from a single, unique backtrace:
An ASCII tree with matched allocations:
Exports matched allocations as a flamegraph:
Exports matched allocations into a format accepted by flamegraph.pl:
Exports matched allocations into a format accepted by Heaptrack GUI:
JSON containing a list of
JSON containing a list of
<id> can either be an actual ID of a loaded data file which you can get by querying
/list endpoint, or can be equal to
last which will use the last loaded data file.
<allocation_filter> can be composed of any of the following parameters:
to- a timestamp in seconds or a percentage (of total runtime) specifying the chronological range of matched allocations
lifetime- an enum specifying the lifetime of matched allocations:
all- matches every allocation (default)
only_leaked- matches only leaked allocations
only_not_deallocated_in_current_range- matches allocation which were not deallocated in the interval specified by
only_deallocated_in_current_range- matches allocations which were deallocated in the interval specified by
only_temporary- matches only temporary allocations
only_whole_group_leaked- matches only allocations whose whole group (that is - every allocation from a given call site) was leaked
address_max- an integer with a minimum/maximum address of matched allocations
size_max- an integer with a minimum/maximum size of matched allocations in bytes
lifetime_max- an integer with a minimum/maximum lifetime of matched allocations in seconds
function_regex- a regexp which needs to match with one of the functions in the backtrace of the matched allocation
source_regex- a regexp which needs to match with one of the source files in the backtrace of the matched allocation
negative_function_regex- a regexp which needs to NOT match with all of the functions in the backtrace of the matched allocation
negative_source_regex- a regexp which needs to NOT match with all of the source files in the backtrace of the matched allocation
group_interval_max- a minimum/maximum interval in seconds or a percentage (of total runtime) between the first and the last allocation from the same call site
group_allocations_max- an integer with a minimum/maximum number of allocations from the same call site
group_leaked_allocations_max- an integer or a percentage of all allocations which were leaked from the same call site
<sort_by> for allocations can be one of:
<group_sort_by> for allocation groups can be one of:
only_matched.* variants will sort by aggregate values derived only from allocations
which were matched by the
allocation_filter, while the
all.* variants will sort
by values derived from every allocation in a given group.
<order> specifies the ordering of the results and can be either
Environment variables used by
A path to a file to which the data will be written to.
This environment variable supports placeholders which will be replaced at runtime with the following:
%p-> PID of the process
%t-> number of seconds since UNIX epoch
%e-> name of the executable
The log level to use; possible values:
Unset by default, which disables logging altogether.
Path to the file to which the logs will be written to; if unset the logs will
be emitted to stderr (if they're enabled with
This supports placeholders similar to
When set to
1 the tracing will be disabled be default at startup.
You can then send
SIGUSR1 to the process to resume tracing at any moment.
When set to
1 the profiled process will send UDP broadcasts announcing that it's being profiled.
This is used by
memory-profiler-gather to automatically detect
to which to connect.
Decides whenever timestamps will be gathered for every event, or only for chunks for events. When enabled the timestamps will be more precise at a cost of extra CPU usage.
malloc will behave like
calloc and fill the memory it returns with zeros.
Whenever to use a more intrusive, faster unwinding algorithm; enabled by default.
Setting it to
0 will on average significantly slow down unwinding. This option
is provided only for debugging purposes.
Enabling full debug logs
By default the profiler is compiled with most of its debug logs disabled for performance reasons.
To reenable them be sure to recompile it with the
debug-logs feature, e.g. like this:
$ cd preload $ cargo build --release --features debug-logs
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.