Command Line Interface
Install the memlab command line tool with npm:
npm install -g memlab
COMMON Commands
memlab run
Find memory leaks in web apps
memlab run --scenario <TEST_SCENARIO_FILE>
examples
memlab run --scenario /tmp/test-scenario.js
memlab run --scenario /tmp/test-scenario.js --work-dir /tmp/test-1/
Options:
--work-dir: set the working directory of the current run--headful: start the browser in headful mode, by default it is headless--full: take heap snapshot for every step in E2E interaction--skip-screenshot: skip taking screenshots--skip-gc: skip doing garbage collection in browser--skip-scroll: skip scrolling target page in browser--skip-extra-ops: skip doing extra interactions (e.g., scrolling and waiting) on target and final page--local-puppeteer: enable remote browser instance debugging via local puppeteer--scenario: set file path loading test scenario--chromium-binary: set the chromium binary for E2E run--protocol-timeout: set the protocol timeout for chromium connection (in ms). The current default value is 180000, you may want to increase the timeout via this flag when the heap snapshot is too big (e.g., over 1GB) and the Page crashed with error: 'ProtocolError: HeapProfiler.takeHeapSnapshot timed out'.--device: set the device type to emulate--user-agent: set the UserAgent string in browser (for E2E interaction), otherwise it uses the default UserAgent from Chromium--disable-xvfb: disable Xvfb (X virtual framebuffer) for simulating headful browser rendering--disable-web-security: disable web security in Chromium to enable cross domain requests; web security is enabled by default--rewrite-js: enable instrument JavaScript code in browser--log-script: enable intercepting and logging JavaScript code in browser--worker: set title of the target (worker) that needs to be selected and analyzed--leak-filter: specify a definition JS file for leak filter--trace-object-size-above: objects with retained size (bytes) bigger than the threshold will be considered as leaks--ignore-leak-cluster-size-below: ignore memory leaks with aggregated retained size smaller than the threshold (in bytes)--trace-all-objects: dump retainer trace for all allocated objects (ignore the leak filter), available option modes: --trace-all-objects=selected-js-objects, --trace-all-objects=default--save-trace-as-unclassified-cluster: dump each retainer trace as an unclassified trace cluster--ml-clustering: use machine learning algorithms for clustering leak traces (by default, traces are clustered by heuristics)--ml-linkage-max-dist: set linkage max distance value for clustering. The value should be between [0, 1] inclusive.--ml-clustering-max-df: set percentage based max document frequency for limiting the terms that appear too often--clean-up-snapshot: clean up heap snapshots after running--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab find-leaks
Find memory leaks in heap snapshots
There are three ways to specify inputs for the memlab find-leaks command:
--baseline,--target,--finalspecifies each heap snapshot input individually;--snapshot-dirspecifies the directory that holds all three heap snapshot files (MemLab will assign baseline, target, and final based on alphabetic order of the file);--work-dirspecifies the output working directory of thememlab runor thememlab snapshotcommand;
Please only use one of the three ways to specify the input.
You can also manually take heap snapshots in Chrome Devtools, save them to disk. Then process them using this command with the CLI flags (either option 1 or option 2 mentioned above).
# check memory leaks in the default working directory generated by
# memlab run (without setting the --work-dir option)
memlab find-leaks
examples
# specify the baseline, target, and final heap snapshot file path separately
memlab find-leaks --baseline /tmp/baseline.heapsnapshot --target /tmp/target.heapsnapshot --final /tmp/final.heapsnapshot
# specifies the directory that holds all three heap snapshot files
memlab find-leaks --snapshot-dir /dir/containing/heapsnapshot/files/
# specifies the output working directory of the `memlab run` or the `memlab snapshot` command
memlab find-leaks --work-dir /memlab/working/dir/generated/by/memlab/
Options:
--baseline: set file path of the baseline heap snapshot--target: set file path of the target heap snapshot--final: set file path of the final heap snapshot--snapshot-dir: set directory path containing all heap snapshots under analysis--engine: set the JavaScript engine (default to V8)--leak-filter: specify a definition JS file for leak filter--trace-object-size-above: objects with retained size (bytes) bigger than the threshold will be considered as leaks--ignore-leak-cluster-size-below: ignore memory leaks with aggregated retained size smaller than the threshold (in bytes)--trace-all-objects: dump retainer trace for all allocated objects (ignore the leak filter), available option modes: --trace-all-objects=selected-js-objects, --trace-all-objects=default--save-trace-as-unclassified-cluster: dump each retainer trace as an unclassified trace cluster--ml-clustering: use machine learning algorithms for clustering leak traces (by default, traces are clustered by heuristics)--ml-linkage-max-dist: set linkage max distance value for clustering. The value should be between [0, 1] inclusive.--ml-clustering-max-df: set percentage based max document frequency for limiting the terms that appear too often--clean-up-snapshot: clean up heap snapshots after running--work-dir: set the working directory of the current run--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab diff-leaks
Find new memory leaks by diffing control and test heap snapshots
memlab diff-leaks
Options:
--control-snapshot: set the single (target) snapshot of control run--control-work-dir: set the working directory of the control run--treatment-snapshot: set the single (target) snapshot of treatment run--treatment-work-dir: set the working directory of the treatment run--engine: set the JavaScript engine (default to V8)--leak-filter: specify a definition JS file for leak filter--trace-object-size-above: objects with retained size (bytes) bigger than the threshold will be considered as leaks--ignore-leak-cluster-size-below: ignore memory leaks with aggregated retained size smaller than the threshold (in bytes)--trace-all-objects: dump retainer trace for all allocated objects (ignore the leak filter), available option modes: --trace-all-objects=selected-js-objects, --trace-all-objects=default--save-trace-as-unclassified-cluster: dump each retainer trace as an unclassified trace cluster--ml-clustering: use machine learning algorithms for clustering leak traces (by default, traces are clustered by heuristics)--ml-linkage-max-dist: set linkage max distance value for clustering. The value should be between [0, 1] inclusive.--ml-clustering-max-df: set percentage based max document frequency for limiting the terms that appear too often--max-cluster-sample-size: specify the max number of leak traces as input to leak trace clustering algorithm. Big sample size will preserve more complete inforrmation, but may risk out-of-memory crash.--trace-contains: set the node name or edge name to filter leak traces that contain the name--work-dir: set the working directory of the current run--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab trace
Report retainer trace of a specific node, use with --nodeId
memlab trace --node-id=<HEAP_OBJECT_ID>
examples
memlab trace --node-id=@3123123
memlab trace --node-id=128127
Options:
--snapshot: set file path of the heap snapshot under analysis--snapshot-dir: set directory path containing all heap snapshots under analysis--engine: set the JavaScript engine (default to V8)--node-id: set heap node ID--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze
Run heap analysis on heap snapshots.
memlab analyze <PLUGIN_NAME> [PLUGIN_OPTIONS]
Options:
--analysis-plugin: specify the external heap analysis plugin file (must be a vanilla JS file ended withAnalysis.jssuffix)--work-dir: set the working directory of the current run--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze unbound-collection
Check unbound collection growth (e.g., Map with growing number of entries)
memlab analyze unbound-collection
Options:
--snapshot-dir: set directory path containing all heap snapshots under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze collections-with-stale
Analyze collections holding stale objects
memlab analyze collections-with-stale
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze detached-DOM
Get detached DOM elements
memlab analyze detached-DOM
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze global-variable
Get global variables in heap
memlab analyze global-variable
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze object
Get properties inside an object
memlab analyze object
Options:
--snapshot: set file path of the heap snapshot under analysis--node-id: set heap node ID--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze object-fanout
Get objects with the most out-going references in heap
memlab analyze object-fanout
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze object-shallow
Get objects by key and value, without recursing into sub-objects
memlab analyze object-shallow
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze shape
List the shapes that retained most memory
memlab analyze shape
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze object-size
Get the largest objects in heap
memlab analyze object-size
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze unbound-object
Check unbound object growth (a single object with growing retained size)
memlab analyze unbound-object
Options:
--snapshot-dir: set directory path containing all heap snapshots under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze react-hooks
Show a memory breakdown of the most memory-consuming React components and their React hooks. This works best with unminified heap snapshots taken from React apps running in Dev mode. But also supports minified heap snapshots taken from React apps in production mode.
memlab analyze react-hooks
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze unbound-shape
Get shapes with unbound growth (a class of objects with growing aggregated retained size)
memlab analyze unbound-shape
Options:
--snapshot-dir: set directory path containing all heap snapshots under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze string
Find duplicated string instances in heap
memlab analyze string
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab analyze unmounted-fiber-node
Get unmounted React Fiber nodes
memlab analyze unmounted-fiber-node
Options:
--snapshot: set file path of the heap snapshot under analysis--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab heap
Interactive command to explore a single heap snapshot
memlab heap --snapshot <HEAP_SNAPSHOT_FILE>
Options:
--snapshot: set file path of the heap snapshot under analysis--engine: set the JavaScript engine (default to V8)--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab view-heap
Interactive command to view a single heap snapshot
memlab view-heap --snapshot <HEAP_SNAPSHOT_FILE>
Options:
--snapshot: set file path of the heap snapshot under analysis--engine: set the JavaScript engine (default to V8)--node-id: set heap node ID--ml-clustering: use machine learning algorithms for clustering leak traces (by default, traces are clustered by heuristics)--work-dir: set the working directory of the current run--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
MISC Commands
memlab version
Show the versions of all memlab packages installed
memlab version
Options:
--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab list
List all test scenarios
memlab list
Options:
--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab reset
Reset and initialize all directories
memlab reset
Options:
--work-dir: set the working directory of the current run--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab measure
Run test scenario in measure mode
In some web apps, the heap size can show considerable variability across various runs. This fluctuation can often make it hard to understand the impact of memory leaks. The introduction of the measure mode aims to address this challenge by executing the same scenario repetitively, therefore getting multiple data points of JavaScript heap sizes. This can help understand if the heap size movements during specific runs come from memory-related issues or just noise.
memlab measure --scenario <TEST_SCENARIO_FILE>
examples
memlab measure --scenario /tmp/test-scenario.js
memlab measure --scenario /tmp/test-scenario.js --work-dir /tmp/test-1/
Options:
--headful: start the browser in headful mode, by default it is headless--run-num: set number of runs--app: set name for onboarded web application--interaction: set name for onboarded interaction--full: take heap snapshot for every step in E2E interaction--skip-snapshot: skip taking heap snapshots--skip-screenshot: skip taking screenshots--skip-gc: skip doing garbage collection in browser--skip-scroll: skip scrolling target page in browser--skip-extra-ops: skip doing extra interactions (e.g., scrolling and waiting) on target and final page--run-mode: set running mode--local-puppeteer: enable remote browser instance debugging via local puppeteer--scenario: set file path loading test scenario--chromium-binary: set the chromium binary for E2E run--protocol-timeout: set the protocol timeout for chromium connection (in ms). The current default value is 180000, you may want to increase the timeout via this flag when the heap snapshot is too big (e.g., over 1GB) and the Page crashed with error: 'ProtocolError: HeapProfiler.takeHeapSnapshot timed out'.--device: set the device type to emulate--user-agent: set the UserAgent string in browser (for E2E interaction), otherwise it uses the default UserAgent from Chromium--disable-xvfb: disable Xvfb (X virtual framebuffer) for simulating headful browser rendering--disable-web-security: disable web security in Chromium to enable cross domain requests; web security is enabled by default--rewrite-js: enable instrument JavaScript code in browser--log-script: enable intercepting and logging JavaScript code in browser--work-dir: set the working directory of the current run--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab warmup
Warm up the target app
memlab warmup --scenario <TEST_SCENARIO_FILE>
examples
memlab warmup --scenario /tmp/test-scenario.js
Options:
--headful: start the browser in headful mode, by default it is headless--app: set name for onboarded web application--interaction: set name for onboarded interaction--run-mode: set running mode--local-puppeteer: enable remote browser instance debugging via local puppeteer--scenario: set file path loading test scenario--chromium-binary: set the chromium binary for E2E run--protocol-timeout: set the protocol timeout for chromium connection (in ms). The current default value is 180000, you may want to increase the timeout via this flag when the heap snapshot is too big (e.g., over 1GB) and the Page crashed with error: 'ProtocolError: HeapProfiler.takeHeapSnapshot timed out'.--device: set the device type to emulate--user-agent: set the UserAgent string in browser (for E2E interaction), otherwise it uses the default UserAgent from Chromium--disable-xvfb: disable Xvfb (X virtual framebuffer) for simulating headful browser rendering--disable-web-security: disable web security in Chromium to enable cross domain requests; web security is enabled by default--skip-warmup: skip warming up web server--rewrite-js: enable instrument JavaScript code in browser--log-script: enable intercepting and logging JavaScript code in browser--work-dir: set the working directory of the current run--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab help
List all MemLab CLI commands or print helper text for a specific command
memlab help <COMMAND> [SUB-COMMANDS]
Options:
--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab get-default-work-dir
Query the default working directory
memlab get-default-work-dir
Options:
--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab snapshot
Interact with web app and take heap snapshots
memlab snapshot --scenario <TEST_SCENARIO_FILE>
examples
memlab snapshot --scenario /tmp/test-scenario.js
memlab snapshot --scenario /tmp/test-scenario.js --work-dir /tmp/test-1/
Options:
--headful: start the browser in headful mode, by default it is headless--app: set name for onboarded web application--interaction: set name for onboarded interaction--full: take heap snapshot for every step in E2E interaction--skip-snapshot: skip taking heap snapshots--skip-screenshot: skip taking screenshots--skip-gc: skip doing garbage collection in browser--skip-scroll: skip scrolling target page in browser--skip-extra-ops: skip doing extra interactions (e.g., scrolling and waiting) on target and final page--run-mode: set running mode--local-puppeteer: enable remote browser instance debugging via local puppeteer--scenario: set file path loading test scenario--chromium-binary: set the chromium binary for E2E run--protocol-timeout: set the protocol timeout for chromium connection (in ms). The current default value is 180000, you may want to increase the timeout via this flag when the heap snapshot is too big (e.g., over 1GB) and the Page crashed with error: 'ProtocolError: HeapProfiler.takeHeapSnapshot timed out'.--device: set the device type to emulate--user-agent: set the UserAgent string in browser (for E2E interaction), otherwise it uses the default UserAgent from Chromium--disable-xvfb: disable Xvfb (X virtual framebuffer) for simulating headful browser rendering--disable-web-security: disable web security in Chromium to enable cross domain requests; web security is enabled by default--rewrite-js: enable instrument JavaScript code in browser--log-script: enable intercepting and logging JavaScript code in browser--worker: set title of the target (worker) that needs to be selected and analyzed--work-dir: set the working directory of the current run--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output
memlab warmup-and-snapshot
Warm up server and take heap snapshots
This is equivalent to running memlab warmup and memlab snapshot.
# specify a test scenario file, memlab will warm up the server and take heap snapshots
memlab warmup-and-snapshot --scenario <TEST_SCENARIO_FILE>
examples
memlab warmup-and-snapshot --scenario /tmp/test-scenario.js
# set the working directory of the current run
memlab warmup-and-snapshot --scenario /tmp/test-scenario.js --work-dir /tmp/test-1/
Options:
--work-dir: set the working directory of the current run--headful: start the browser in headful mode, by default it is headless--app: set name for onboarded web application--interaction: set name for onboarded interaction--run-mode: set running mode--local-puppeteer: enable remote browser instance debugging via local puppeteer--scenario: set file path loading test scenario--chromium-binary: set the chromium binary for E2E run--protocol-timeout: set the protocol timeout for chromium connection (in ms). The current default value is 180000, you may want to increase the timeout via this flag when the heap snapshot is too big (e.g., over 1GB) and the Page crashed with error: 'ProtocolError: HeapProfiler.takeHeapSnapshot timed out'.--device: set the device type to emulate--user-agent: set the UserAgent string in browser (for E2E interaction), otherwise it uses the default UserAgent from Chromium--disable-xvfb: disable Xvfb (X virtual framebuffer) for simulating headful browser rendering--disable-web-security: disable web security in Chromium to enable cross domain requests; web security is enabled by default--skip-warmup: skip warming up web server--rewrite-js: enable instrument JavaScript code in browser--log-script: enable intercepting and logging JavaScript code in browser--full: take heap snapshot for every step in E2E interaction--skip-snapshot: skip taking heap snapshots--skip-screenshot: skip taking screenshots--skip-gc: skip doing garbage collection in browser--skip-scroll: skip scrolling target page in browser--skip-extra-ops: skip doing extra interactions (e.g., scrolling and waiting) on target and final page--worker: set title of the target (worker) that needs to be selected and analyzed--help,-h: print helper text--verbose,-v: show more details--sc: set to continuous test mode--debug: enable manual debugging--silent,-s: mute all terminal output