MemLab

A framework for finding JavaScript memory leaks and analyzing heap snapshot...

PerformanceTesting
facebook/memlabfacebook.github.io/memlab/memlab

README

memlab

Licensed under the MIT License PR's Welcome npm version

memlab is an E2E testing and analysis framework for finding JavaScript memory
leaks and optimization opportunities.

Online Resources:
Official Website and Demo
Documentation
Meta Engineering Blog Post

Features:
Browser memory leak detection - Write test scenario with puppeteer API,
   memlab auto diffs JS heap snapshots, filters out memory leaks, and
   aggregates results.
Object-oriented heap traversing API - Supports self-defined memory leak
   detector and programmatically analyzing 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 memory leaks)
Memory assertions in Node.js - Enables unit test or running node.js
   program to take a heap snapshot of its own state, do self memory checking,
   or write advanced memory assertions

CLI Usage


Install the CLI

  1. ``` sh
  2. npm install -g memlab
  3. ```

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 test-google-maps.js:

  1. ``` js
  2. // initial page load url: Google Maps
  3. function url() {
  4.   return 'https://www.google.com/maps/@37.386427,-122.0428214,11z';
  5. }

  7. // action where we want to detect memory leaks: click the Hotels button
  8. async function action(page) {
  9.   // puppeteer page API
  10.   await page.click('button[aria-label="Hotels"]');
  11. }

  13. // action where we want to go back to the step before: click clear search
  14. async function back(page) {
  15.   // puppeteer page API
  16.   await page.click('[aria-label="Clear search"]');
  17. }

  19. module.exports = {action, back, url};
  20. ```

Now run memlab with the scenario file, memlab will interact with
the web page and detect memory leaks with built-in leak detectors:

  1. ``` sh
  2. memlab run --scenario test-google-maps.js
  3. ```

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).

  1. ``` sh
  2. MemLab found 46 leak(s)
  3. --Similar leaks in this run: 4--
  4. --Retained size of leaked objects: 8.3MB--
  5. [Window] (native) @35847 [8.3MB]
  6.   --20 (element)--->  [InternalNode] (native) @130981728 [8.3MB]
  7.   --8 (element)--->  [InternalNode] (native) @130980288 [8.3MB]
  8.   --1 (element)--->  [EventListener] (native) @131009888 [8.3MB]
  9.   --1 (element)--->  [V8EventListener] (native) @224808192 [8.3MB]
  10.   --1 (element)--->  [eventHandler] (closure) @168079 [8.3MB]
  11.   --context (internal)--->  [<function scope>] (object) @181905 [8.3MB]
  12.   --bigArray (variable)--->  [Array] (object) @182925 [8.3MB]
  13.   --elements (internal)--->  [(object elements)] (array) @182929 [8.3MB]
  14. ...
  15. ```
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 $(memlab get-default-work-dir)/data/cur)
in Chrome DevTool and search for the leaked object ID (@182929).

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:
  1. ``` sh
  2. memlab view-heap --snapshot <PATH TO .heapsnapshot FILE>
  3. ```

You can optionally specify a specific heap object with the object's id: --node-id @28173 to pinpoint a specific object.

heap-view

Self-defined leak detector: If you want to use a self-defined leak detector, add a leakFilter callback
(doc)
in the scenario file. filterLeak will be called for every unreleased heap
object (node) allocated by the target interaction.

  1. ``` js
  2. function leakFilter(node, heap) {
  3.   // ... your leak detector logic
  4.   // return true to mark the node as a memory leak
  5. };
  6. ```

heap 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:
  1. ``` sh
  2. memlab analyze unbound-object
  3. ```

Analyze pre-fetched V8/hermes .heapsnapshot files:

  1. ``` sh
  2. memlab analyze unbound-object --snapshot-dir <DIR_OF_SNAPSHOT_FILES>
  3. ```

Use memlab analyze to view all built-in memory analyses.
For extension, view the doc site.

View retainer trace of a particular object:
  1. ``` sh
  2. memlab trace --node-id <HEAP_OBJECT_ID>
  3. ```

Use memlab help to view all CLI commands.

APIs


Use the memlab npm package to start a E2E run in browser and detect memory leaks.

  1. ``` js
  2. const memlab = require('memlab');

  4. const scenario = {
  5.     // initial page load url
  6.     url: () => 'https://www.google.com/maps/@37.386427,-122.0428214,11z',

  8.     // action where we want to detect memory leaks
  9.     action: async (page) => await page.click('button[aria-label="Hotels"]'),

  11.     // action where we want to go back to the step before
  12.     back: async (page) => await page.click('[aria-label="Clear search"]'),
  13. }
  14. memlab.run({scenario});
  15. ```

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:

  1. ```typescript
  2. // save as example.test.ts
  3. import type {IHeapSnapshot, Nullable} from '@memlab/core';
  4. import {config, takeNodeMinimalHeap} from '@memlab/core';

  6. class TestObject {
  7.   public arr1 = [1, 2, 3];
  8.   public arr2 = ['1', '2', '3'];
  9. }

  11. test('memory test with heap assertion', async () => {
  12.   config.muteConsole = true; // no console output

  14.   let obj: Nullable<TestObject> = new TestObject();
  15.   // get a heap snapshot of the current program state
  16.   let heap: IHeapSnapshot = await takeNodeMinimalHeap();

  18.   // call some function that may add references to obj
  19.   rabbitHole(obj)

  21.   expect(heap.hasObjectWithClassName('TestObject')).toBe(true);
  22.   obj = null;

  24.   heap = await takeNodeMinimalHeap();
  25.   // if rabbitHole does not have any side effect that
  26.   // adds new references to obj, then obj can be GCed
  27.   expect(heap.hasObjectWithClassName('TestObject')).toBe(false);

  29. }, 30000);
  30. ```

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:

  1. ``` sh
  2. npm install
  3. npm run build
  4. ```

Then keep this helper script running to ensure that local changes are picked up
and compiled automatically during development:

  1. ``` sh
  2. npm run dev
  3. ```

NOTE: To run the memlab cli locally, make sure to prefix the memlab command with
npx from within the memlab repo e.g. npx memlab

Run tests:
  1. ``` sh
  2. npm run test
  3. ```

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.