Introduction
MemScout is a companion visualization and analysis tool for the jemalloc memory allocator.
It sifts through profile dumps generated by the allocator, extracts useful information
and presents it in a clean and easily readable format for the user. Understanding allocator
performance for any resource-heavy or misssion critical application is crucial as it can reveal
pathological memory allocation behavior and shed a light on easily overlooked resource wastage. We
have used MemScout extensively to detect such issues in production services and have applied fixes
that have led to notable performance wins.
Using MemScout
MemScout reads the profile dumps produced by jemalloc. Profiling is not enabled by default in the allocator. In order to enable profiling with jemalloc, the user must export the following environment variable prior to launching the binary:
export MALLOC_CONF="prof:true,prof_prefix:jeprof.out"
The user can further control the profile sample rate and dumping interval with the
lg_prof_sample and lg_prof_interval flags, respectively. For detailed instructions on how to
enable heap profiling with jemalloc, please refer to the documentation here: jemalloc Heap
Profiling.
The generated profile dumps are JSON files which can be parsed by MemScout. In order to start
MemScout locally on your machine, simply clone (git clone [email protected]:facebook/memscout.git) or download the repo to a directory and use a browser to
navigate to the page. For instance, if the repor was cloned into ~/Documents/memscout/, the user
can access the tool at ~/Documents/memscout/index.html in any browser. On the landing page, the
user may upload a jemalloc profile dump file (JSON formatted) via the file upload interface. Once
uploaded, MemScout will populate the appropriate sections of the UI with data and graphs extracted
from the dump file.
Testing with provided example
A sample jemalloc profile dump file is included in the root directory (example_heap_profile.txt). In
order to understand the metrics being displayed in the charts, we recommend that the user upload
this file and walk though the different segments of the UI.
License
MemScout uses the MIT License, as found in the LICENSE file.