@memlab/core 1.1.21 → 1.1.23

package/dist/__tests__/lib/TestUtils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 web_perf_infra
+ */
+import { IHeapSnapshot } from '../../lib/Types';
+/** @internal */
+export declare function getFullHeapFromFile(file: string): Promise<IHeapSnapshot>;
+//# sourceMappingURL=TestUtils.d.ts.map

package/dist/__tests__/lib/TestUtils.js

@@ -0,0 +1,39 @@
+"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 web_perf_infra
+ */
+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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFullHeapFromFile = void 0;
+const __1 = require("../..");
+/** @internal */
+function getFullHeapFromFile(file) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return yield loadProcessedSnapshot({ file });
+    });
+}
+exports.getFullHeapFromFile = getFullHeapFromFile;
+function loadProcessedSnapshot(options = {}) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const opt = { buildNodeIdIndex: true, verbose: true };
+        const file = options.file || __1.utils.getSnapshotFilePathWithTabType(/.*/);
+        const snapshot = yield __1.utils.getSnapshotFromFile(file, opt);
+        __1.analysis.preparePathFinder(snapshot);
+        __1.info.flush();
+        return snapshot;
+    });
+}

package/dist/lib/Config.d.ts

@@ -38,6 +38,11 @@ declare type ConfigOption = {
     workDir?: string;
 };
 /** @internal */
+export declare enum TraceObjectMode {
+    Default = 1,
+    SelectedJSObjects = 2
+}
+/** @internal */
 export declare enum ErrorHandling {
     Halt = 1,
     Throw = 2
@@ -109,7 +114,7 @@ export declare class MemLabConfig {
     qes: QuickExperiment[];
     isOndemand: boolean;
     useExternalSnapshot: boolean;
-    externalRunMetaFile: string;
+    externalRunMetaTemplateFile: string;
     externalSnapshotVisitOrderFile: string;
     externalSnapshotDir: Nullable<string>;
     externalSnapshotFilePaths: string[];
@@ -177,6 +182,7 @@ export declare class MemLabConfig {
     nodeIgnoreSetInShape: Set<string>;
     oversizeObjectAsLeak: boolean;
     oversizeThreshold: number;
+    traceAllObjectsMode: TraceObjectMode;
     clusterRetainedSizeThreshold: number;
     externalLeakFilter?: Optional<ILeakFilter>;
     monoRepoDir: string;
@@ -199,6 +205,9 @@ export declare class MemLabConfig {
     interceptScript: boolean;
     isAnalyzingMainThread: boolean;
     targetWorkerTitle: Nullable<string>;
+    noReCluster: boolean;
+    maxSamplesForClustering: number;
+    filterTraceByName: Nullable<string>;
     constructor(options?: ConfigOption);
     private initInternalConfigs;
     private init;

package/dist/lib/Config.js

@@ -35,7 +35,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemLabConfig = exports.ErrorHandling = void 0;
+exports.MemLabConfig = exports.ErrorHandling = exports.TraceObjectMode = void 0;
 const path_1 = __importDefault(require("path"));
 const RunningModes_1 = __importDefault(require("../modes/RunningModes"));
 const Console_1 = __importDefault(require("./Console"));
@@ -57,6 +57,12 @@ const defaultViewport = {
     deviceScaleFactor: 1,
 };
 /** @internal */
+var TraceObjectMode;
+(function (TraceObjectMode) {
+    TraceObjectMode[TraceObjectMode["Default"] = 1] = "Default";
+    TraceObjectMode[TraceObjectMode["SelectedJSObjects"] = 2] = "SelectedJSObjects";
+})(TraceObjectMode = exports.TraceObjectMode || (exports.TraceObjectMode = {}));
+/** @internal */
 var ErrorHandling;
 (function (ErrorHandling) {
     ErrorHandling[ErrorHandling["Halt"] = 1] = "Halt";
@@ -176,12 +182,17 @@ class MemLabConfig {
         // if true, split dataset into trunks
         // with random order for sequential clustering
         this.seqClusteringIsRandomChunks = false;
+        // maximum number of samples as input for leak trace clustering
+        this.maxSamplesForClustering = 5000;
         // extra E2E run info (other than the fields defined in
         // RunMetaInfo like app, interaction, browserInfo).
         // Information saved in this map will be
         // auto-serialized to run-meta.json when the file is saved
         // and auto-deserialized from run-meta.json when the file is loaded
         this.extraRunInfoMap = new Map();
+        // if specified via CLI options, this will filter leak traces by
+        // node and edge names in the leak trace
+        this.filterTraceByName = null;
     }
     // initialize configurable parameters
     init(options = {}) {
@@ -209,6 +220,8 @@ class MemLabConfig {
         this.skipGC = false;
         // true if running in ContinuousTest
         this.isContinuousTest = false;
+        // true if reclustering is turned off
+        this.noReCluster = false;
         // true if running a local test
         this.isTest = false;
         // true if running in local puppeteer mode
@@ -308,7 +321,10 @@ class MemLabConfig {
         // node names excluded from the trace finding
         this.nodeNameBlockList = new Set(['system / PropertyCell']);
         // edge names excluded from the trace finding
-        this.edgeNameBlockList = new Set(['feedback_cell']);
+        this.edgeNameBlockList = new Set([
+            'feedback_cell',
+            'part of key -> value pair in ephemeron table',
+        ]);
         // node names less preferable in trace finding
         this.nodeNameGreyList = new Set([
             'InternalNode',
@@ -341,6 +357,9 @@ class MemLabConfig {
         this.oversizeObjectAsLeak = false;
         // if larger than this threshold, consider as memory leak
         this.oversizeThreshold = 0;
+        // when specified default, this mode will trace/diff all objects
+        // you can specified other modes (e.g., selected JS objects only)
+        this.traceAllObjectsMode = TraceObjectMode.Default;
         // only report leak clusters with aggregated retained size
         // bigger than this threshold
         this.clusterRetainedSizeThreshold = 0;

package/dist/lib/Constant.js

@@ -46,6 +46,7 @@ const constants = {
         '(Write barrier)',
         '(Retain maps)',
         '(Unknown)',
+        '<Synthetic>',
     ],
     namePrefixForScenarioFromFile: '',
     unset: 'UNSET',

package/dist/lib/FileManager.js

@@ -427,7 +427,7 @@ class FileManager {
         config.heapAnalysisLogDir = joinAndProcessDir(options, this.getHeapAnalysisLogDir(options));
         config.metricsOutDir = joinAndProcessDir(options, loggerOutDir, 'metrics');
         config.reportScreenshotFile = path_1.default.join(outDir, 'report.png');
-        config.externalRunMetaFile = this.getRunMetaExternalTemplateFile();
+        config.externalRunMetaTemplateFile = this.getRunMetaExternalTemplateFile();
         config.externalSnapshotVisitOrderFile =
             this.getSnapshotSequenceExternalTemplateFile();
         joinAndProcessDir(options, this.getUniqueTraceClusterDir(options));

package/dist/lib/HeapAnalyzer.js

@@ -35,6 +35,7 @@ const TraceBucket_1 = __importDefault(require("../trace-cluster/TraceBucket"));
 const LeakObjectFilter_1 = require("./leak-filters/LeakObjectFilter");
 const MLTraceSimilarityStrategy_1 = __importDefault(require("../trace-cluster/strategies/MLTraceSimilarityStrategy"));
 const LeakTraceFilter_1 = require("./trace-filters/LeakTraceFilter");
+const TraceSampler_1 = __importDefault(require("./TraceSampler"));
 class MemoryAnalyst {
     checkLeak() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -48,13 +49,13 @@ class MemoryAnalyst {
             const controlSnapshotDirs = options.controlWorkDirs.map(controlWorkDir => FileManager_1.default.getCurDataDir({
                 workDir: controlWorkDir,
             }));
-            const treatmentSnapshotDir = FileManager_1.default.getCurDataDir({
-                workDir: options.treatmentWorkDir,
-            });
+            const treatmentSnapshotDirs = options.treatmentWorkDirs.map(treatmentWorkDir => FileManager_1.default.getCurDataDir({
+                workDir: treatmentWorkDir,
+            }));
             // check control working dir
             controlSnapshotDirs.forEach(controlSnapshotDir => Utils_1.default.checkSnapshots({ snapshotDir: controlSnapshotDir }));
             // check treatment working dir
-            Utils_1.default.checkSnapshots({ snapshotDir: treatmentSnapshotDir });
+            treatmentSnapshotDirs.forEach(treatmentSnapshotDir => Utils_1.default.checkSnapshots({ snapshotDir: treatmentSnapshotDir }));
             // display control and treatment memory
             MemoryBarChart_1.default.plotMemoryBarChart(options);
             return this.diffMemoryLeakTraces(options);
@@ -75,17 +76,26 @@ class MemoryAnalyst {
                 leakPathsFromControlRuns.push(this.filterLeakPaths(snapshotDiff.leakedHeapNodeIdSet, snapshotDiff.snapshot, { workDir: controlWorkDir }));
                 controlSnapshots.push(snapshotDiff.snapshot);
             }
-            // diff snapshots and get treatment raw paths
-            const snapshotDiff = yield this.diffSnapshots({
-                loadAllSnapshots: true,
-                workDir: options.treatmentWorkDir,
-            });
-            const treatmentLeakPaths = this.filterLeakPaths(snapshotDiff.leakedHeapNodeIdSet, snapshotDiff.snapshot, { workDir: options.treatmentWorkDir });
-            const treatmentSnapshot = snapshotDiff.snapshot;
+            // diff snapshots from treatment dirs and get treatment raw paths array
+            const treatmentSnapshots = [];
+            const leakPathsFromTreatmentRuns = [];
+            let firstTreatmentSnapshotDiff = null;
+            for (const treatmentWorkDir of options.treatmentWorkDirs) {
+                const snapshotDiff = yield this.diffSnapshots({
+                    loadAllSnapshots: true,
+                    workDir: treatmentWorkDir,
+                });
+                if (firstTreatmentSnapshotDiff == null) {
+                    firstTreatmentSnapshotDiff = snapshotDiff;
+                }
+                leakPathsFromTreatmentRuns.push(this.filterLeakPaths(snapshotDiff.leakedHeapNodeIdSet, snapshotDiff.snapshot, { workDir: treatmentWorkDir }));
+                treatmentSnapshots.push(snapshotDiff.snapshot);
+            }
             const controlPathCounts = JSON.stringify(leakPathsFromControlRuns.map(leakPaths => leakPaths.length));
+            const treatmentPathCounts = JSON.stringify(leakPathsFromTreatmentRuns.map(leakPaths => leakPaths.length));
             Console_1.default.topLevel(`${controlPathCounts} traces from control group`);
-            Console_1.default.topLevel(`${treatmentLeakPaths.length} traces from treatment group`);
-            const result = TraceBucket_1.default.clusterControlTreatmentPaths(leakPathsFromControlRuns, controlSnapshots, treatmentLeakPaths, treatmentSnapshot, Utils_1.default.aggregateDominatorMetrics, {
+            Console_1.default.topLevel(`${treatmentPathCounts} traces from treatment group`);
+            const result = TraceBucket_1.default.clusterControlTreatmentPaths(leakPathsFromControlRuns, controlSnapshots, leakPathsFromTreatmentRuns, treatmentSnapshots, Utils_1.default.aggregateDominatorMetrics, {
                 strategy: Config_1.default.isMLClustering
                     ? new MLTraceSimilarityStrategy_1.default()
                     : undefined,
@@ -94,7 +104,10 @@ class MemoryAnalyst {
             yield this.serializeClusterUpdate(result.treatmentOnlyClusters);
             // serialize JSON file with detailed leak trace information
             const treatmentOnlyPaths = result.treatmentOnlyClusters.map(c => c.path);
-            return LeakTraceDetailsLogger_1.default.logTraces(snapshotDiff.leakedHeapNodeIdSet, snapshotDiff.snapshot, snapshotDiff.listOfLeakedHeapNodeIdSet, treatmentOnlyPaths, Config_1.default.traceJsonOutDir);
+            if (firstTreatmentSnapshotDiff == null) {
+                throw Utils_1.default.haltOrThrow('treatemnt snapshot diff result not found');
+            }
+            return LeakTraceDetailsLogger_1.default.logTraces(firstTreatmentSnapshotDiff.leakedHeapNodeIdSet, firstTreatmentSnapshotDiff.snapshot, firstTreatmentSnapshotDiff.listOfLeakedHeapNodeIdSet, treatmentOnlyPaths, Config_1.default.traceJsonOutDir);
         });
     }
     // find all unique pattern of leaks
@@ -357,26 +370,35 @@ class MemoryAnalyst {
         this.filterLeakedObjects(leakedNodeIds, snapshot);
         const leakTraceFilter = new LeakTraceFilter_1.LeakTraceFilter();
         const nodeIdInPaths = new Set();
-        const paths = [];
-        let numOfLeakedObjects = 0;
-        let i = 0;
+        const samplePool = [];
         // analysis for each node
         Utils_1.default.applyToNodes(leakedNodeIds, snapshot, node => {
-            if (!Config_1.default.isContinuousTest && ++i % 11 === 0) {
-                Console_1.default.overwrite(`progress: ${i} / ${leakedNodeIds.size} @${node.id}`);
-            }
             // BFS search for path from the leaked node to GC roots
             const p = finder.getPathToGCRoots(snapshot, node);
             if (p == null ||
                 !leakTraceFilter.filter(p, { config: Config_1.default, leakedNodeIds, snapshot })) {
                 return;
             }
-            ++numOfLeakedObjects;
-            paths.push(p);
-            this.logLeakTraceSummary(p, nodeIdInPaths, snapshot, options);
+            // filter leak trace based on CLI-specified node or edge names
+            if (!Utils_1.default.pathHasNodeOrEdgeWithName(p, Config_1.default.filterTraceByName)) {
+                return;
+            }
+            // ignore if the leak trace is too long
+            if (Utils_1.default.getLeakTracePathLength(p) > 100) {
+                return;
+            }
+            samplePool.push(p);
         }, { reverse: true });
+        const sampler = new TraceSampler_1.default(samplePool.length);
+        const paths = samplePool.filter(p => {
+            if (sampler.sample()) {
+                this.logLeakTraceSummary(p, nodeIdInPaths, snapshot, options);
+                return true;
+            }
+            return false;
+        });
         if (Config_1.default.verbose) {
-            Console_1.default.midLevel(`${numOfLeakedObjects} leaked objects`);
+            Console_1.default.midLevel(`Filter and select ${paths.length} leaked trace`);
         }
         return paths;
     }
@@ -410,11 +432,11 @@ class MemoryAnalyst {
     clusterHeapObjects(objectIds, snapshot) {
         const finder = this.preparePathFinder(snapshot);
         const paths = [];
-        let i = 0;
+        const sampler = new TraceSampler_1.default(objectIds.size);
         // analysis for each node
         Utils_1.default.applyToNodes(objectIds, snapshot, node => {
-            if (++i % 11 === 0) {
-                Console_1.default.overwrite(`progress: ${i} / ${objectIds.size} @${node.id}`);
+            if (!sampler.sample()) {
+                return;
             }
             // BFS search for path from the leaked node to GC roots
             const p = finder.getPathToGCRoots(snapshot, node);

package/dist/lib/RunInfoUtils.d.ts

@@ -11,6 +11,7 @@ import type { Nullable, Optional, RunMetaInfo } from './Types';
 export declare class RunMetaInfoManager {
     getRunMetaFilePath(options?: {
         workDir?: Optional<string>;
+        readonly?: Optional<boolean>;
     }): string;
     saveRunMetaInfo(runMetaInfo: RunMetaInfo, options?: {
         workDir?: Optional<string>;

package/dist/lib/RunInfoUtils.js

@@ -16,8 +16,10 @@ class RunMetaInfoManager {
         if ((options === null || options === void 0 ? void 0 : options.workDir) != null) {
             return FileManager_1.default.getRunMetaFile({ workDir: options.workDir });
         }
-        if (Config_1.default.useExternalSnapshot) {
-            return Config_1.default.externalRunMetaFile;
+        if ((options === null || options === void 0 ? void 0 : options.readonly) && Config_1.default.useExternalSnapshot) {
+            // only returns the template file if the
+            // run meta file is used for readonly purpose
+            return Config_1.default.externalRunMetaTemplateFile;
         }
         if (Config_1.default.runMetaFile != null) {
             return Config_1.default.runMetaFile;
@@ -40,7 +42,8 @@ class RunMetaInfoManager {
         return runMetaInfo;
     }
     loadRunMetaInfo(options) {
-        const file = (options === null || options === void 0 ? void 0 : options.metaFile) || this.getRunMetaFilePath(options);
+        const file = (options === null || options === void 0 ? void 0 : options.metaFile) ||
+            this.getRunMetaFilePath(Object.assign({ readonly: true }, options));
         try {
             return this.loadRunMetaInfoFromFile(file);
         }
@@ -49,7 +52,8 @@ class RunMetaInfoManager {
         }
     }
     loadRunMetaInfoSilentFail(options) {
-        const file = (options === null || options === void 0 ? void 0 : options.metaFile) || this.getRunMetaFilePath(options);
+        const file = (options === null || options === void 0 ? void 0 : options.metaFile) ||
+            this.getRunMetaFilePath(Object.assign({ readonly: true }, options));
         try {
             return this.loadRunMetaInfoFromFile(file);
         }

package/dist/lib/SerializationHelper.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 web_perf_infra
+ */
+import type { IHeapNode, IHeapSnapshot, ISerializationHelper, ISerializedInfo, JSONifyArgs, JSONifyOptions, Nullable } from './Types';
+export declare class SerializationHelper implements ISerializationHelper {
+    protected snapshot: Nullable<IHeapSnapshot>;
+    setSnapshot(snapshot: IHeapSnapshot): void;
+    createOrMergeWrapper(info: ISerializedInfo, _node: IHeapNode, _args: JSONifyArgs, _options: JSONifyOptions): ISerializedInfo;
+}
+declare const _default: typeof SerializationHelper;
+export default _default;
+//# sourceMappingURL=SerializationHelper.d.ts.map

package/dist/lib/SerializationHelper.js

@@ -0,0 +1,36 @@
+"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 web_perf_infra
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SerializationHelper = void 0;
+const InternalValueSetter_1 = require("./InternalValueSetter");
+const Constant_1 = __importDefault(require("./Constant"));
+class SerializationHelper {
+    constructor() {
+        this.snapshot = null;
+    }
+    setSnapshot(snapshot) {
+        this.snapshot = snapshot;
+    }
+    createOrMergeWrapper(info, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _node, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _args, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options) {
+        return info;
+    }
+}
+exports.SerializationHelper = SerializationHelper;
+exports.default = (0, InternalValueSetter_1.setInternalValue)(SerializationHelper, __filename, Constant_1.default.internalDir);

package/dist/lib/Serializer.d.ts

@@ -7,12 +7,8 @@
  * @format
  * @oncall web_perf_infra
  */
-import { E2EStepInfo, HeapNodeIdSet, IHeapEdge, IHeapNode, IHeapSnapshot, ISerializedInfo, LeakTracePathItem, Nullable } from './Types';
-declare type JSONifyArgs = {
-    leakedIdSet?: Set<number>;
-    nodeIdsInSnapshots?: Array<Set<number>>;
-};
-declare function JSONifyPath(path: LeakTracePathItem, _snapshot: IHeapSnapshot, args: JSONifyArgs): Nullable<ISerializedInfo>;
+import { E2EStepInfo, HeapNodeIdSet, IHeapEdge, IHeapNode, IHeapSnapshot, ISerializedInfo, JSONifyArgs, LeakTracePathItem, Nullable } from './Types';
+declare function JSONifyPath(path: LeakTracePathItem, snapshot: IHeapSnapshot, args: JSONifyArgs): Nullable<ISerializedInfo>;
 declare type SummarizeOptions = {
     compact?: boolean;
     color?: boolean;

package/dist/lib/Serializer.js

@@ -18,6 +18,7 @@ const Config_1 = __importDefault(require("./Config"));
 const Utils_1 = __importDefault(require("./Utils"));
 const Console_1 = __importDefault(require("./Console"));
 const TraceFinder_1 = __importDefault(require("../paths/TraceFinder"));
+const SerializationHelper_1 = __importDefault(require("./SerializationHelper"));
 const REGEXP_NAME_CLEANUP = /[[]\(\)]/g;
 const EMPTY_JSONIFY_OPTIONS = {
     fiberNodeReturnTrace: {},
@@ -374,7 +375,12 @@ function JSONifyNode(node, args, options) {
     if (node.dominatorNode) {
         info['dominator id (extra)'] = `@${node.dominatorNode.id}`;
     }
-    return info;
+    // use serialization helper to wrap around
+    // the JSON node with additional tagging information
+    const { serializationHelper } = options;
+    return serializationHelper
+        ? serializationHelper.createOrMergeWrapper(info, node, args, options)
+        : info;
 }
 function JSONifyTabsOrder() {
     const file = Utils_1.default.getSnapshotSequenceFilePath();
@@ -383,7 +389,7 @@ function JSONifyTabsOrder() {
 function shouldHighlight(node) {
     return Utils_1.default.isDetachedDOMNode(node) || Utils_1.default.isDetachedFiberNode(node);
 }
-function JSONifyPath(path, _snapshot, args) {
+function JSONifyPath(path, snapshot, args) {
     if (!path.node) {
         return null;
     }
@@ -393,6 +399,9 @@ function JSONifyPath(path, _snapshot, args) {
     ret['$tabsOrder:' + JSONifyTabsOrder()] = '';
     ret[`${idx++}: ${getNodeNameInJSON(path.node, args)}`] = JSONifyNode(path.node, args, Object.assign(Object.assign({}, EMPTY_JSONIFY_OPTIONS), { processedNodeId: new Set() }));
     let pathItem = path;
+    // initialize serialization helper
+    const serializationHelper = new SerializationHelper_1.default();
+    serializationHelper.setSnapshot(snapshot);
     while (pathItem === null || pathItem === void 0 ? void 0 : pathItem.edge) {
         const edge = pathItem.edge;
         const nextNode = edge.toNode;
@@ -401,7 +410,7 @@ function JSONifyPath(path, _snapshot, args) {
             nextNode.highlight = true;
         }
         const edgeRetainSize = pathItem.edgeRetainSize;
-        ret[`${idx++}: ${getEdgeNameInJSON(edge, edgeRetainSize)}${getNodeNameInJSON(nextNode, args)}`] = JSONifyNode(nextNode, args, Object.assign(Object.assign({}, EMPTY_JSONIFY_OPTIONS), { processedNodeId: new Set() }));
+        ret[`${idx++}: ${getEdgeNameInJSON(edge, edgeRetainSize)}${getNodeNameInJSON(nextNode, args)}`] = JSONifyNode(nextNode, args, Object.assign(Object.assign({}, EMPTY_JSONIFY_OPTIONS), { processedNodeId: new Set(), serializationHelper }));
         pathItem = pathItem.next;
     }
     return ret;

package/dist/lib/TraceSampler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 web_perf_infra
+ */
+export declare type TraceSamplerOption = {
+    maxSample?: number;
+};
+export default class TraceSampler {
+    private maxCount;
+    private processed;
+    private selected;
+    private population;
+    constructor(n: number, options?: TraceSamplerOption);
+    init(n: number): void;
+    private calculateSampleRatio;
+    /**
+     * The caller decide to give up sampling this time.
+     * This `giveup` and the `sample` method in aggregation should be
+     * called `this.population` times.
+     *
+     * For example, if `giveup` is called n1 times,
+     * and `sample` is called n2 times, then n1 + n2 === this.population.
+     */
+    giveup(): void;
+    /**
+     * This sample method should be called precisely this.population times.
+     * @returns true if this sample should be taken
+     */
+    sample(): boolean;
+}
+//# sourceMappingURL=TraceSampler.d.ts.map

package/dist/lib/TraceSampler.js

@@ -0,0 +1,78 @@
+"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 web_perf_infra
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const Config_1 = __importDefault(require("./Config"));
+const Console_1 = __importDefault(require("./Console"));
+const Utils_1 = __importDefault(require("./Utils"));
+class TraceSampler {
+    constructor(n, options = {}) {
+        var _a;
+        // the max number of traces after sampling
+        this.maxCount = Config_1.default.maxSamplesForClustering;
+        this.processed = 0;
+        this.selected = 0;
+        this.population = -1;
+        this.maxCount = (_a = options.maxSample) !== null && _a !== void 0 ? _a : Config_1.default.maxSamplesForClustering;
+        this.init(n);
+    }
+    init(n) {
+        this.processed = 0;
+        this.selected = 0;
+        this.population = n;
+        this.calculateSampleRatio(n);
+    }
+    calculateSampleRatio(n) {
+        const sampleRatio = Math.min(1, this.maxCount / n);
+        if (sampleRatio < 1) {
+            Console_1.default.warning('Sampling trace due to a large number of traces:');
+            Console_1.default.lowLevel(` Number of Traces: ${n}`);
+            Console_1.default.lowLevel(` Sampling Ratio: ${Utils_1.default.getReadablePercent(sampleRatio)}`);
+        }
+        return sampleRatio;
+    }
+    /**
+     * The caller decide to give up sampling this time.
+     * This `giveup` and the `sample` method in aggregation should be
+     * called `this.population` times.
+     *
+     * For example, if `giveup` is called n1 times,
+     * and `sample` is called n2 times, then n1 + n2 === this.population.
+     */
+    giveup() {
+        ++this.processed;
+    }
+    /**
+     * This sample method should be called precisely this.population times.
+     * @returns true if this sample should be taken
+     */
+    sample() {
+        if (this.processed >= this.population) {
+            throw Utils_1.default.haltOrThrow(`processing ${this.processed + 1} samples but total population is ${this.population}`);
+        }
+        // use large number to mod here to avoid too much console I/O
+        if (!Config_1.default.isContinuousTest && this.processed % 771 === 0) {
+            const percent = Utils_1.default.getReadablePercent(this.processed / this.population);
+            Console_1.default.overwrite(`progress: ${this.processed} / ${this.population} (${percent})`);
+        }
+        const dynamicRatio = (this.maxCount - this.selected) / (this.population - this.processed);
+        // increase the counter indicating how many samples has been processed
+        ++this.processed;
+        if (Math.random() <= dynamicRatio) {
+            ++this.selected;
+            return true;
+        }
+        return false;
+    }
+}
+exports.default = TraceSampler;

package/dist/lib/Types.d.ts

@@ -806,8 +806,9 @@ export declare type TraceClusterMetaInfo = {
 };
 /** @internal */
 export declare type ControlTreatmentClusterResult = {
-    controlOnlyClusters: TraceCluster[];
+    controlLikelyOrOnlyClusters: TraceCluster[];
     treatmentOnlyClusters: TraceCluster[];
+    treatmentLikelyClusters: TraceCluster[];
     hybridClusters: Array<{
         control: TraceCluster;
         treatment: TraceCluster;
@@ -1930,12 +1931,12 @@ export interface IOveralLeakInfo extends Partial<IOveralHeapInfo> {
 /** @internal */
 export declare type DiffLeakOptions = {
     controlWorkDirs: string[];
-    treatmentWorkDir: string;
+    treatmentWorkDirs: string[];
 };
 /** @internal */
 export declare type PlotMemoryOptions = {
     controlWorkDirs?: string[];
-    treatmentWorkDir?: string;
+    treatmentWorkDirs?: string[];
     workDir?: string;
 } & IMemoryAnalystOptions;
 /** @internal */
@@ -1971,4 +1972,26 @@ export interface IHeapConfig {
 }
 /** @internal */
 export declare type ErrorWithMessage = Pick<Error, 'message'>;
+/** @internal */
+export declare type CommandOptionExample = string | {
+    description?: string;
+    cliOptionExample: string;
+};
+/** @internal */
+export declare type JSONifyArgs = {
+    leakedIdSet?: Set<number>;
+    nodeIdsInSnapshots?: Array<Set<number>>;
+};
+/** @internal */
+export interface ISerializationHelper {
+    setSnapshot(snapshot: IHeapSnapshot): void;
+    createOrMergeWrapper(info: ISerializedInfo, node: IHeapNode, args: JSONifyArgs, options: JSONifyOptions): ISerializedInfo;
+}
+/** @internal */
+export declare type JSONifyOptions = {
+    fiberNodeReturnTrace: Record<number, string>;
+    processedNodeId: Set<number>;
+    forceJSONifyDepth?: number;
+    serializationHelper?: ISerializationHelper;
+};
 //# sourceMappingURL=Types.d.ts.map