@memlab/heap-analysis 1.0.9 → 1.0.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/PluginUtils.d.ts

@@ -314,18 +314,24 @@ declare function aggregateDominatorMetrics(ids: Set<number>, snapshot: IHeapSnap
  */
 declare function getDominatorNodes(ids: Set<number>, snapshot: IHeapSnapshot): Set<number>;
 declare function filterOutLargestObjects(snapshot: IHeapSnapshot, objectFilter: (node: IHeapNode) => boolean, listSize?: number): IHeapNode[];
+declare function calculateRetainedSizes(snapshot: IHeapSnapshot): void;
+declare function isCollectObject(node: IHeapNode): boolean;
+declare function getCollectionFanout(node: IHeapNode): number;
 declare const _default: {
     aggregateDominatorMetrics: typeof aggregateDominatorMetrics;
+    calculateRetainedSizes: typeof calculateRetainedSizes;
     defaultAnalysisArgs: {
         args: {
             _: never[];
         };
     };
     filterOutLargestObjects: typeof filterOutLargestObjects;
+    getCollectionFanout: typeof getCollectionFanout;
     getDominatorNodes: typeof getDominatorNodes;
     getObjectOutgoingEdgeCount: typeof getObjectOutgoingEdgeCount;
     getSnapshotDirForAnalysis: typeof getSnapshotDirForAnalysis;
     getSnapshotFileForAnalysis: typeof getSnapshotFileForAnalysis;
+    isCollectObject: typeof isCollectObject;
     isNodeWorthInspecting: typeof isNodeWorthInspecting;
     loadHeapSnapshot: typeof loadHeapSnapshot;
     getHeapFromFile: typeof getHeapFromFile;

package/dist/PluginUtils.js

@@ -604,14 +604,49 @@ function filterOutLargestObjects(snapshot, objectFilter, listSize = 50) {
     });
     return largeObjects;
 }
+function calculateRetainedSizes(snapshot) {
+    const finder = new core_2.TraceFinder();
+    // dominator and retained size
+    finder.calculateAllNodesRetainedSizes(snapshot);
+}
+function isCollectObject(node) {
+    if (node.type !== 'object') {
+        return false;
+    }
+    return (node.name === 'Map' ||
+        node.name === 'Set' ||
+        node.name === 'WeakMap' ||
+        node.name === 'WeakSet');
+}
+function getCollectionFanout(node) {
+    if (node.type !== 'object') {
+        return 0;
+    }
+    if (node.name === 'Array') {
+        return node.edge_count;
+    }
+    else if (node.name === 'Map' ||
+        node.name === 'Set' ||
+        node.name === 'WeakMap' ||
+        node.name === 'WeakSet') {
+        const table = node.getReferenceNode('table');
+        if (table) {
+            return table.edge_count;
+        }
+    }
+    return 0;
+}
 exports.default = {
     aggregateDominatorMetrics,
+    calculateRetainedSizes,
     defaultAnalysisArgs,
     filterOutLargestObjects,
+    getCollectionFanout,
     getDominatorNodes,
     getObjectOutgoingEdgeCount,
     getSnapshotDirForAnalysis,
     getSnapshotFileForAnalysis,
+    isCollectObject,
     isNodeWorthInspecting,
     loadHeapSnapshot,
     getHeapFromFile,

package/dist/plugins/CollectionUnboundGrowthAnalysis.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall ws_labs
+ */
+import type { HeapAnalysisOptions } from '../PluginUtils';
+import type { BaseOption } from '@memlab/core';
+import BaseAnalysis from '../BaseAnalysis';
+declare class CollectionUnboundGrowthAnalysis extends BaseAnalysis {
+    getCommandName(): string;
+    /** @internal */
+    getDescription(): string;
+    /** @internal */
+    getOptions(): BaseOption[];
+    /** @internal */
+    analyzeSnapshotFromFile(file: string): Promise<void>;
+    /** @internal */
+    process(options: HeapAnalysisOptions): Promise<void>;
+    private checkUnboundCollection;
+}
+export default CollectionUnboundGrowthAnalysis;
+//# sourceMappingURL=CollectionUnboundGrowthAnalysis.d.ts.map

package/dist/plugins/CollectionUnboundGrowthAnalysis.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall ws_labs
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const core_1 = require("@memlab/core");
+const BaseAnalysis_1 = __importDefault(require("../BaseAnalysis"));
+const HeapAnalysisSnapshotDirectoryOption_1 = __importDefault(require("../options/HeapAnalysisSnapshotDirectoryOption"));
+const PluginUtils_1 = __importDefault(require("../PluginUtils"));
+const __1 = require("..");
+class CollectionUnboundGrowthAnalysis extends BaseAnalysis_1.default {
+    getCommandName() {
+        return 'unbound-collection';
+    }
+    /** @internal */
+    getDescription() {
+        return ('Check unbound collection growth ' +
+            '(e.g., Map with growing number of entries)');
+    }
+    /** @internal */
+    getOptions() {
+        return [new HeapAnalysisSnapshotDirectoryOption_1.default()];
+    }
+    /** @internal */
+    analyzeSnapshotFromFile(file) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const f = file;
+            throw core_1.utils.haltOrThrow(`${this.constructor.name} does not support analyzeSnapshotFromFile`);
+        });
+    }
+    /** @internal */
+    process(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const snapshotDir = PluginUtils_1.default.getSnapshotDirForAnalysis(options);
+            const opt = snapshotDir ? { minSnapshots: 2, snapshotDir } : {};
+            core_1.config.chaseWeakMapEdge = false;
+            core_1.analysis.visualizeMemoryUsage(opt);
+            core_1.utils.checkSnapshots(opt);
+            yield this.checkUnboundCollection(opt);
+        });
+    }
+    checkUnboundCollection(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const nodeInfo = Object.create(null);
+            let hasCheckedFirstSnapshot = false;
+            let snapshot = null;
+            const initNodeInfo = (node) => {
+                if (!__1.PluginUtils.isCollectObject(node)) {
+                    return;
+                }
+                const n = __1.PluginUtils.getCollectionFanout(node);
+                nodeInfo[node.id] = {
+                    type: node.type,
+                    name: node.name,
+                    min: n,
+                    max: n,
+                    history: [n],
+                    node,
+                };
+            };
+            const updateNodeInfo = (node) => {
+                const item = nodeInfo[node.id];
+                if (!item) {
+                    return;
+                }
+                if (node.name !== item.name || node.type !== item.type) {
+                    nodeInfo[node.id] = null;
+                    return;
+                }
+                const n = __1.PluginUtils.getCollectionFanout(node);
+                // only monotonic increase?
+                if (core_1.config.monotonicUnboundGrowthOnly && n < item.max) {
+                    nodeInfo[node.id] = null;
+                    return;
+                }
+                item.history.push(n);
+                item.max = Math.max(item.max, n);
+                item.min = Math.min(item.min, n);
+            };
+            core_1.info.overwrite('Checking unbounded collections...');
+            const snapshotFiles = options.snapshotDir
+                ? // load snapshots from a directory
+                    core_1.utils.getSnapshotFilesInDir(options.snapshotDir)
+                : // load snapshots based on the visit sequence meta data
+                    core_1.utils.getSnapshotFilesFromTabsOrder();
+            for (const file of snapshotFiles) {
+                // force GC before loading each snapshot
+                if (global.gc) {
+                    global.gc();
+                }
+                // load and preprocess heap snapshot
+                const opt = { buildNodeIdIndex: true, verbose: true };
+                snapshot = yield core_1.utils.getSnapshotFromFile(file, opt);
+                __1.PluginUtils.calculateRetainedSizes(snapshot);
+                // keep track of heap objects
+                if (!hasCheckedFirstSnapshot) {
+                    // record Ids in the snapshot
+                    snapshot.nodes.forEach(initNodeInfo);
+                    hasCheckedFirstSnapshot = true;
+                }
+                else {
+                    snapshot.nodes.forEach(updateNodeInfo);
+                }
+            }
+            // exit if no heap snapshot found
+            if (!hasCheckedFirstSnapshot) {
+                return;
+            }
+            // post process and print the unbounded objects
+            const idsInLastSnapshot = new Set();
+            snapshot === null || snapshot === void 0 ? void 0 : snapshot.nodes.forEach(node => {
+                idsInLastSnapshot.add(node.id);
+            });
+            let ids = [];
+            for (const key in nodeInfo) {
+                const id = parseInt(key, 10);
+                const item = nodeInfo[id];
+                if (!item) {
+                    continue;
+                }
+                if (!idsInLastSnapshot.has(id)) {
+                    continue;
+                }
+                if (item.min === item.max) {
+                    continue;
+                }
+                ids.push(Object.assign({ id }, item));
+            }
+            if (ids.length === 0) {
+                core_1.info.midLevel('No increasing collections found.');
+                return;
+            }
+            ids = ids
+                .sort((o1, o2) => o2.history[o2.history.length - 1] - o1.history[o1.history.length - 1])
+                .slice(0, 20);
+            const formatter = (n) => `${n}`;
+            ids.forEach(item => (item.historyNumberFormatter = formatter));
+            // print on terminal
+            const str = core_1.serializer.summarizeUnboundedObjects(ids, { color: true });
+            core_1.info.topLevel('Top growing objects in sizes:');
+            core_1.info.lowLevel(' (Use `memlab trace --node-id=@ID` to get trace)');
+            core_1.info.topLevel('\n' + str);
+            // save results to file
+            const csv = core_1.serializer.summarizeUnboundedObjectsToCSV(ids);
+            fs_1.default.writeFileSync(core_1.config.unboundObjectCSV, csv, 'UTF-8');
+        });
+    }
+}
+exports.default = CollectionUnboundGrowthAnalysis;

package/dist/plugins/ObjectUnboundGrowthAnalysis.js

@@ -31,7 +31,8 @@ class ObjectUnboundGrowthAnalysis extends BaseAnalysis_1.default {
     }
     /** @internal */
     getDescription() {
-        return 'Check unbound object growth';
+        return ('Check unbound object growth ' +
+            '(a single object with growing retained size)');
     }
     /** @internal */
     getOptions() {

package/dist/plugins/ShapeUnboundGrowthAnalysis.js

@@ -37,7 +37,8 @@ class ShapeUnboundGrowthAnalysis extends BaseAnalysis_1.default {
     }
     /** @internal */
     getDescription() {
-        return 'Get shapes with unbound growth';
+        return ('Get shapes with unbound growth ' +
+            '(a class of objects with growing aggregated retained size)');
     }
     /** @internal */
     getOptions() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/heap-analysis",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "license": "MIT",
   "description": "heap analysis plugins for memlab",
   "author": "Liang Gong <lgong@fb.com>",
@@ -16,7 +16,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "LICENSE"
   ],
   "dependencies": {
     "@memlab/core": "^1.1.10",