facebook / memlab

MemLab memlab is an end-to-end testing and analysis framework for identifying JavaScript memory leaks and optimization opportunities. **Online Resources:** [Website and Demo] | [Documentation] | [Meta Engineering Blog Post] Features: • **Browser memory leak detection** - Write test scenarios with the Puppeteer API, and memlab will automatically compare JavaScript heap snapshots, filter out memory leaks, and aggregate the results • **Object-oriented heap traversing API** - Supports the creation of self-defined memory leak detector, and enables programmatic analysis of JS heap snapshots taken from Chromium-based browsers, Node.js, Electron.js, and Hermes • **Memory CLI toolbox** - Built-in toolbox and APIs for finding memory optimization opportunities (not necessarily just memory leaks) • **MemLens: Browser Memory Debugging Tools** - Enables visualization of memory leaks and interactive memory debugging in the browser. • **Memory assertions in Node.js** - Enables unit tests or running node.js programs to take a heap snapshot of their own state, perform self memory checking, or write advanced memory assertions CLI Usage Install the CLI Find Memory Leaks To find memory leaks in Google Maps, you can create a scenario file defining how to interact with the Google Maps, let's name it : Now run memlab with the scenario file, memlab will interact with the web page and detect memory leaks with built-in leak detectors: memlab will print memory leak results showing one representative retainer trace for each cluster of leaked objects. **Retainer traces**: This is the result from an example website, the retainer trace is an object reference chain from the GC root to a leaked object. The trace shows why and how a leaked object is still kept alive in memory. Breaking the reference chain means the leaked object will no longer be reachable from the GC root, and therefore can be garbage collected. By following the leak trace one step at a time, you will be able to find a reference that should be set to null (but it wasn't due to a bug). To get readable trace, the web site under test needs to serve non-minified code (or at least minified code with readable variables, function name, and property names on objects). Alternatively, you can debug the leak by loading the heap snapshot taken by memlab (saved in ) in Chrome DevTool and search for the leaked object ID ( ). **View Retainer Trace Interactively** View memory issues detected by memlab based on a single JavaScript heap snapshot taken from Chromium, Hermes, memlab, or any node.js or Electron.js program: You can optionally specify a specific heap object with the object's id: to pinpoint a specific object. **Self-defined leak detector**: If you want to use a self-defined leak detector, add a callback (doc) in the scenario file. will be called for every unreleased heap object ( ) allocated by the target interaction. is the graph representation of the final JavaScript heap snapshot. For more details, view the doc site. Heap Analysis and Investigation View which object keeps growing in size during interaction in the previous run: Analyze pre-fetched V8/hermes files: Use to view all built-in memory analyses. For extension, view the doc site. View retainer trace of a particular object: Use to view all CLI commands. APIs Use the npm package to start a E2E run in browser and detect memory leaks. Visual Debugging for Memory Leaks in Browser Please check out this tutorial page on how to use MemLens (a debugging utility) to visualize memory leaks in the browser for easier memory debugging. Memory Assertions memlab makes it possible to enable a unit test or running node.js program to take a heap snapshot of its own state, and write advanced memory assertions: For other APIs check out the API documentation. Development Use node version 16 or above. To build on Windows, please use Git Bash. First build the project as follows: Then keep this helper script running to ensure that local changes are picked up and compiled automatically during development: NOTE: To run the memlab cli locally, make sure to prefix the memlab command with npx from within the memlab repo e.g. Run tests: License memlab is MIT licensed, as found in the LICENSE file. Contributing Check our contributing guide to learn about how to contribute to the project. Code of Conduct Check our Code Of Conduct to learn more about our contributor standards and expectations.