Repository files navigation

allocscope is a tool for tracking down where the most egregiously large allocations are occurringin a C, C++ or Rust codebase. It is particilarly intendend to be useful for developers who want toget a handle on excessive allocations and are working in a large codebase with multiplecontributors with allocations occuring in many modules or libraries.

It is composed of two commands:

allocscope-trace attaches to another process as a debugger. By using breakpoints on memoryallocation functions such asmalloc it tracks allocations made by that process. During thetrace, the callstack of all allocations are recorded to an.atrace file. Tracing programswhich spawn multiple threads and tracing calls through shared libraries are supported. You canspawn a process to trace by specifying a full commandline toallocscope-trace, or you canattach to an existing running process.

allocscope-view reads the.atrace file produced byallocscope-trace. It presents a summaryof all allocations made in a call tree format, which can be sorted by largest concurrentallocation, total number of blocks, number of unfreed allocation blocks, or the sequence ofthe allocation. The summary can be navigated interactively through a curses-based terminal userinterface, or a text report suitable for non-interactive use can be generated.

The easiest way to get started with allocscope is to install prebuilt binaries.

To install the latest version:

curl -s https://allocscope.com/install.sh | sudo sh

Currently only Linux on x86_64 processors is supported, but I'd like to support more operating systemsand processors in the future.

While it will likely be most useful to use allocscope on a program with symbols, which youhave compiled yourself, you can verify that it functions correctly by performing a trace on astandard system command, such asls:

allocscope-trace ls -lallocscope-view ls.atrace

On recent Ubuntu releases, allocscope can be built from source with the following sequenceof commands:

apt-get updateapt-get install cargo git libclang-dev libiberty-dev libncurses-dev libsqlite3-dev libunwind-devgit clone https://github.com/matt-kimball/allocscope.gitcd allocscopecargo install --path allocscope-tracecargo install --path allocscope-view

If you are modifying the functionality of allocscope, you can run integration tests by executingthetest.sh script in the root directory of the repository.

Statically linked binaries can also be built using thebuild-static/build.sh script, though this requiresDocker installed on the build system.

If you find allocscope useful, please consider supporting development.

Visithttps://allocscope.com/support

allocscope is licensed GNU General Public License version 3.