@memlab/heap-analysis 2.0.5 → 2.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,143 @@
1
- ## memlab Heap Analysis
1
+ # @memlab/heap-analysis
2
2
 
3
- This is the memlab heap analysis library. It contains all memlab built-in heap analysis and
4
- provides a plugin interface for adding new heap analysis that can be easily added to memlab API and memlab CLI.
3
+ memlab's heap analyses, and the plugin interface for writing your own. Each
4
+ analysis reads one or more JavaScript heap snapshots and reports a kind of
5
+ memory problem: duplicated strings, detached DOM, objects or collections that
6
+ keep growing, and more. Not every problem is a leak.
7
+
8
+ The same analyses run from the `memlab analyze` command and from code. The
9
+ snapshots can come from Chromium, Node.js, Electron, or Hermes.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ npm install @memlab/heap-analysis
15
+ ```
16
+
17
+ To run the analyses from a terminal instead, install the CLI:
18
+ `npm install -g memlab`.
19
+
20
+ ## Built-in analyses
21
+
22
+ | `memlab analyze ...` | Class | What it reports |
23
+ | --- | --- | --- |
24
+ | `string` | `StringAnalysis` | Duplicated string instances |
25
+ | `detached-DOM` | `DetachedDOMElementAnalysis` | Detached DOM elements |
26
+ | `global-variable` | `GlobalVariableAnalysis` | Global variables |
27
+ | `object-size` | `ObjectSizeAnalysis` | The largest objects |
28
+ | `object-fanout` | `ObjectFanoutAnalysis` | Objects with the most outgoing references |
29
+ | `object-shallow` | `ObjectShallowAnalysis` | Duplicated objects, compared by key and value without recursing |
30
+ | `shape` | `ObjectShapeAnalysis` | The object shapes that retain the most memory |
31
+ | `collections-with-stale` | `CollectionsHoldingStaleAnalysis` | Collections holding stale objects |
32
+ | `unbound-object` | `ObjectUnboundGrowthAnalysis` | Objects that keep growing across snapshots |
33
+ | `unbound-shape` | `ShapeUnboundGrowthAnalysis` | Shapes that keep growing across snapshots |
34
+ | `unbound-collection` | (CLI only) | Collections whose entry count keeps growing |
35
+ | `unmounted-fiber-node` | (CLI only) | Unmounted React Fiber nodes |
36
+ | `react-hooks` | (CLI only) | Memory breakdown of the largest React components |
37
+ | `object` | (CLI only) | The properties of one object |
38
+
39
+ Run `memlab analyze` to see them all, and `memlab help analyze <name>`
40
+ for an analysis's options.
41
+
42
+ ## Run an analysis from the CLI
43
+
44
+ On a single snapshot, for example one saved from Chrome DevTools:
45
+
46
+ ```bash
47
+ memlab analyze string --snapshot /path/to/file.heapsnapshot
48
+ ```
49
+
50
+ On a series of snapshots of the same app, to find growth:
51
+
52
+ ```bash
53
+ memlab analyze unbound-object --snapshot-dir /path/to/snapshots/
54
+ ```
55
+
56
+ Without `--snapshot` or `--snapshot-dir`, memlab uses the snapshots from the
57
+ last `memlab run`.
58
+
59
+ ## Run an analysis from code
60
+
61
+ ```typescript
62
+ import {StringAnalysis, ShapeUnboundGrowthAnalysis} from '@memlab/heap-analysis';
63
+
64
+ (async function () {
65
+ // one snapshot
66
+ const strings = new StringAnalysis();
67
+ // the console output is saved to result.analysisOutputFile
68
+ const result = await strings.analyzeSnapshotFromFile(snapshotFile);
69
+ // structured, analysis-specific results
70
+ const duplicated = strings.getTopDuplicatedStringsInCount();
71
+
72
+ // a directory of snapshots
73
+ const shapes = new ShapeUnboundGrowthAnalysis();
74
+ await shapes.analyzeSnapshotsInDirectory(snapshotDirectory);
75
+ const growing = shapes.getShapesWithUnboundGrowth();
76
+ })();
77
+ ```
78
+
79
+ Both methods accept `{workDir}` to choose where output and intermediate files
80
+ go.
81
+
82
+ ## Write your own analysis
83
+
84
+ Extend `BaseAnalysis`, name it, and implement `process`. `loadHeapSnapshot`
85
+ gives you the parsed heap graph
86
+ ([`IHeapSnapshot`](https://meta.github.io/memlab/docs/api/core/src/interfaces/IHeapSnapshot))
87
+ with retained sizes already computed:
88
+
89
+ ```typescript
90
+ import type {HeapAnalysisOptions} from '@memlab/heap-analysis';
91
+ import {BaseAnalysis, loadHeapSnapshot} from '@memlab/heap-analysis';
92
+
93
+ class LargeArrayAnalysis extends BaseAnalysis {
94
+ public getCommandName(): string {
95
+ return 'large-array';
96
+ }
97
+
98
+ public getDescription(): string {
99
+ return 'List arrays that retain more than 1MB';
100
+ }
101
+
102
+ async process(options: HeapAnalysisOptions): Promise<void> {
103
+ const heap = await loadHeapSnapshot(options);
104
+ heap.nodes.forEach(node => {
105
+ if (node.name === 'Array' && node.retainedSize > 1024 * 1024) {
106
+ console.log(`@${node.id}: ${node.retainedSize} bytes`);
107
+ }
108
+ });
109
+ }
110
+ }
111
+
112
+ (async function () {
113
+ await new LargeArrayAnalysis().analyzeSnapshotFromFile(snapshotFile);
114
+ })();
115
+ ```
116
+
117
+ To run it from the CLI, compile it to a plain JavaScript file whose name ends
118
+ in `Analysis.js` and export the class. Then pass the file with
119
+ `--analysis-plugin`:
120
+
121
+ ```bash
122
+ memlab analyze large-array --analysis-plugin ./LargeArrayAnalysis.js \
123
+ --snapshot /path/to/file.heapsnapshot
124
+ ```
125
+
126
+ ## Other exports
127
+
128
+ | Export | What it does |
129
+ | --- | --- |
130
+ | `getFullHeapFromFile` | Load and parse a `.heapsnapshot` file into a heap graph |
131
+ | `loadHeapSnapshot`, `getSnapshotFileForAnalysis`, `getSnapshotDirForAnalysis` | Find and load the snapshot(s) an analysis was asked to run on |
132
+ | `snapshotMapReduce` | Process a directory of snapshots one at a time, then combine the results |
133
+ | `takeNodeFullHeap` | Snapshot the current Node.js process and return the full heap graph |
134
+ | `getDominatorNodes` | Find the dominator nodes of a set of objects |
135
+
136
+ The full reference is in the
137
+ [API documentation](https://meta.github.io/memlab/docs/api/heap-analysis/src/).
5
138
 
6
139
  ## Online Resources
7
- * [Official Website and Demo](https://facebook.github.io/memlab)
8
- * [Documentation](https://facebook.github.io/memlab/docs/intro)
140
+
141
+ * [Official Website and Demo](https://meta.github.io/memlab)
142
+ * [Documentation](https://meta.github.io/memlab/docs/intro)
143
+ * [`memlab analyze` reference](https://meta.github.io/memlab/docs/cli/analyze/)
@@ -1 +1 @@
1
- {"version":3,"file":"ObjectShallowAnalysis.d.ts","sourceRoot":"","sources":["../../src/plugins/ObjectShallowAnalysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,qBAAqB,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAG/E,OAAO,EAAc,UAAU,EAAY,MAAM,cAAc,CAAC;AAChE,OAAO,YAAY,MAAM,iBAAiB,CAAC;AAS3C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,qDAAqD;IACrD,CAAC,EAAE,MAAM,CAAC;IACV,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAiBF,cAAM,qBAAsB,SAAQ,YAAY;IAC9C,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,sBAAsB,CAAM;IACpC,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,uBAAuB,CAAM;IACrC,OAAO,CAAC,kBAAkB,CAAyB;IAEnD;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB,gBAAgB;IAChB,UAAU,IAAI,UAAU,EAAE;IAI1B,gBAAgB;IACH,2BAA2B,CACtC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC;IAQjC,gBAAgB;IACV,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1D;;;OAGG;IACI,6BAA6B,IAAI,YAAY,EAAE;IAItD,cAAc;IACd,OAAO,CAAC,wBAAwB;IAyBhC,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAGpC;IAEF,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,oCAAoC;IAS5C,OAAO,CAAC,mCAAmC;IAS3C,OAAO,CAAC,iCAAiC;IA6BzC,OAAO,CAAC,KAAK;CA8Cd;AAED,eAAe,qBAAqB,CAAC"}
1
+ {"version":3,"file":"ObjectShallowAnalysis.d.ts","sourceRoot":"","sources":["../../src/plugins/ObjectShallowAnalysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,qBAAqB,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAG/E,OAAO,EAAc,UAAU,EAAY,MAAM,cAAc,CAAC;AAChE,OAAO,YAAY,MAAM,iBAAiB,CAAC;AAS3C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,qDAAqD;IACrD,CAAC,EAAE,MAAM,CAAC;IACV,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAiBF,cAAM,qBAAsB,SAAQ,YAAY;IAC9C,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,sBAAsB,CAAM;IACpC,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,uBAAuB,CAAM;IACrC,OAAO,CAAC,kBAAkB,CAAyB;IAEnD;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB;;;;OAIG;IACH,cAAc,IAAI,MAAM;IAIxB,gBAAgB;IAChB,UAAU,IAAI,UAAU,EAAE;IAI1B,gBAAgB;IACH,2BAA2B,CACtC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC;IAQjC,gBAAgB;IACV,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAS1D;;;OAGG;IACI,6BAA6B,IAAI,YAAY,EAAE;IAItD,cAAc;IACd,OAAO,CAAC,wBAAwB;IAyBhC,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAEpC;IAEF,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,oCAAoC;IAS5C,OAAO,CAAC,mCAAmC;IAS3C,OAAO,CAAC,iCAAiC;IA6BzC,OAAO,CAAC,KAAK;CA8Cd;AAED,eAAe,qBAAqB,CAAC"}
@@ -252,7 +252,6 @@ class ObjectShallowAnalysis extends BaseAnalysis_1.default {
252
252
  }
253
253
  }
254
254
  ObjectShallowAnalysis.objectPatternsToObserve = {
255
- // eslint-disable-next-line @typescript-eslint/no-unused-vars
256
- 'All objects': (_) => true,
255
+ 'All objects': () => true,
257
256
  };
258
257
  exports.default = ObjectShallowAnalysis;
@@ -1 +1 @@
1
- {"version":3,"file":"StringAnalysis.d.ts","sourceRoot":"","sources":["../../src/plugins/StringAnalysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAC,qBAAqB,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAG/E,OAAO,EAAc,UAAU,EAAC,MAAM,cAAc,CAAC;AACrD,OAAO,YAAY,MAAM,iBAAiB,CAAC;AAyB3C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,qDAAqD;IACrD,CAAC,EAAE,MAAM,CAAC;IACV,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,YAAY;IACtD,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,sBAAsB,CAAM;IACpC,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,uBAAuB,CAAM;IACrC,OAAO,CAAC,kBAAkB,CAAyB;IAEnD;;;OAGG;IACI,8BAA8B,IAAI,YAAY,EAAE;IAIvD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAmCpC;IAEF;;;;OAIG;IACI,cAAc,IAAI,MAAM;IAI/B;;;;OAIG;IACI,cAAc,IAAI,MAAM;IAI/B,gBAAgB;IAChB,UAAU,IAAI,UAAU,EAAE;IAI1B,gBAAgB;IACH,2BAA2B,CACtC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC;IAQjC,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAc/B,gBAAgB;IACV,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1D,OAAO,CAAC,wBAAwB;IA8BhC,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,oCAAoC;IAS5C,OAAO,CAAC,mCAAmC;IAS3C,OAAO,CAAC,iCAAiC;IAyCzC,OAAO,CAAC,KAAK;CA4Cd"}
1
+ {"version":3,"file":"StringAnalysis.d.ts","sourceRoot":"","sources":["../../src/plugins/StringAnalysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAC,qBAAqB,EAAE,mBAAmB,EAAC,MAAM,gBAAgB,CAAC;AAG/E,OAAO,EAAc,UAAU,EAAC,MAAM,cAAc,CAAC;AACrD,OAAO,YAAY,MAAM,iBAAiB,CAAC;AAyB3C;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,qDAAqD;IACrD,CAAC,EAAE,MAAM,CAAC;IACV,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,YAAY;IACtD,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,sBAAsB,CAAM;IACpC,OAAO,CAAC,eAAe,CAAsB;IAC7C,OAAO,CAAC,uBAAuB,CAAM;IACrC,OAAO,CAAC,kBAAkB,CAAyB;IAEnD;;;OAGG;IACI,8BAA8B,IAAI,YAAY,EAAE;IAIvD;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAkCpC;IAEF;;;;OAIG;IACI,cAAc,IAAI,MAAM;IAI/B;;;;OAIG;IACI,cAAc,IAAI,MAAM;IAI/B,gBAAgB;IAChB,UAAU,IAAI,UAAU,EAAE;IAI1B,gBAAgB;IACH,2BAA2B,CACtC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC;IAQjC,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAc/B,gBAAgB;IACV,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAa1D,OAAO,CAAC,wBAAwB;IA8BhC,OAAO,CAAC,WAAW;IA0BnB,OAAO,CAAC,oCAAoC;IAS5C,OAAO,CAAC,mCAAmC;IAS3C,OAAO,CAAC,iCAAiC;IAyCzC,OAAO,CAAC,KAAK;CA4Cd"}
@@ -227,8 +227,7 @@ class StringAnalysis extends BaseAnalysis_1.default {
227
227
  */
228
228
  StringAnalysis.stringPatternsToObserve = {
229
229
  // all strings (excluding sliced strings)
230
- // eslint-disable-next-line @typescript-eslint/no-unused-vars
231
- 'All strings': (_) => true,
230
+ 'All strings': () => true,
232
231
  'Relay DataID': (str) => {
233
232
  return str.startsWith('Uzpf');
234
233
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memlab/heap-analysis",
3
- "version": "2.0.5",
3
+ "version": "2.0.7",
4
4
  "license": "MIT",
5
5
  "description": "heap analysis plugins for memlab",
6
6
  "author": "Liang Gong <lgong@meta.com>",
@@ -20,8 +20,8 @@
20
20
  "LICENSE"
21
21
  ],
22
22
  "dependencies": {
23
- "@memlab/core": "^2.0.5",
24
- "@memlab/e2e": "^2.0.5",
23
+ "@memlab/core": "^2.0.7",
24
+ "@memlab/e2e": "^2.0.7",
25
25
  "ansi": "^0.3.1",
26
26
  "babar": "^0.2.0",
27
27
  "chalk": "^4.0.0",
@@ -44,7 +44,7 @@
44
44
  },
45
45
  "repository": {
46
46
  "type": "git",
47
- "url": "git+https://github.com/facebook/memlab.git",
47
+ "url": "git+https://github.com/meta/memlab.git",
48
48
  "directory": "packages/heap-analysis"
49
49
  },
50
50
  "scripts": {
@@ -54,7 +54,7 @@
54
54
  "clean-pkg": "rm -rf ./dist && rm -rf ./node_modules && rm -f ./tsconfig.tsbuildinfo"
55
55
  },
56
56
  "bugs": {
57
- "url": "https://github.com/facebook/memlab/issues"
57
+ "url": "https://github.com/meta/memlab/issues"
58
58
  },
59
- "homepage": "https://github.com/facebook/memlab#readme"
59
+ "homepage": "https://github.com/meta/memlab#readme"
60
60
  }