@memlab/heap-analysis 2.0.6 → 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
|
-
|
|
1
|
+
# @memlab/heap-analysis
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
|
140
|
+
|
|
7
141
|
* [Official Website and Demo](https://meta.github.io/memlab)
|
|
8
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,
|
|
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
|
-
|
|
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,
|
|
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
|
-
|
|
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.
|
|
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.
|
|
24
|
-
"@memlab/e2e": "^2.0.
|
|
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",
|