@memlab/core 1.1.20 → 1.1.22

package/dist/index.d.ts

@@ -26,6 +26,8 @@ export { default as utils } from './lib/Utils';
 /** @internal */
 export { default as fileManager } from './lib/FileManager';
 /** @internal */
+export { default as runInfoUtils } from './lib/RunInfoUtils';
+/** @internal */
 export * from './lib/FileManager';
 /** @internal */
 export { default as serializer } from './lib/Serializer';

package/dist/index.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.TraceFinder = exports.MultiIterationSeqClustering = exports.SequentialClustering = exports.EvaluationMetric = exports.NormalizedTrace = exports.leakClusterLogger = exports.ProcessManager = exports.modes = exports.memoryBarChart = exports.constant = exports.analysis = exports.browserInfo = exports.serializer = exports.fileManager = exports.utils = exports.BaseOption = exports.info = exports.config = exports.registerPackage = void 0;
+exports.TraceFinder = exports.MultiIterationSeqClustering = exports.SequentialClustering = exports.EvaluationMetric = exports.NormalizedTrace = exports.leakClusterLogger = exports.ProcessManager = exports.modes = exports.memoryBarChart = exports.constant = exports.analysis = exports.browserInfo = exports.serializer = exports.runInfoUtils = exports.fileManager = exports.utils = exports.BaseOption = exports.info = exports.config = exports.registerPackage = void 0;
 const path_1 = __importDefault(require("path"));
 const PackageInfoLoader_1 = require("./lib/PackageInfoLoader");
 __exportStar(require("./lib/Types"), exports);
@@ -67,6 +67,9 @@ Object.defineProperty(exports, "utils", { enumerable: true, get: function () { r
 var FileManager_1 = require("./lib/FileManager");
 Object.defineProperty(exports, "fileManager", { enumerable: true, get: function () { return __importDefault(FileManager_1).default; } });
 /** @internal */
+var RunInfoUtils_1 = require("./lib/RunInfoUtils");
+Object.defineProperty(exports, "runInfoUtils", { enumerable: true, get: function () { return __importDefault(RunInfoUtils_1).default; } });
+/** @internal */
 __exportStar(require("./lib/FileManager"), exports);
 /** @internal */
 var Serializer_1 = require("./lib/Serializer");

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
@@ -99,6 +104,7 @@ export declare class MemLabConfig {
     dataBuilderDataDir: string;
     unclassifiedClusterDir: string;
     externalCookiesFile: Optional<string>;
+    extraRunInfoMap: Map<string, string>;
     heapConfig: Optional<IHeapConfig>;
     puppeteerConfig: LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions;
     openDevtoolsConsole: boolean;
@@ -176,6 +182,7 @@ export declare class MemLabConfig {
     nodeIgnoreSetInShape: Set<string>;
     oversizeObjectAsLeak: boolean;
     oversizeThreshold: number;
+    traceAllObjectsMode: TraceObjectMode;
     clusterRetainedSizeThreshold: number;
     externalLeakFilter?: Optional<ILeakFilter>;
     monoRepoDir: string;
@@ -198,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;
@@ -225,6 +235,7 @@ export declare class MemLabConfig {
     setDevice(deviceName: string, options?: {
         manualOverride?: boolean;
     }): void;
+    setRunInfo(key: string, value: string): void;
     private removeFromSet;
     private addToSet;
     enableXvfb(display: string): void;

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,6 +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 = {}) {
@@ -203,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
@@ -335,6 +354,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;
@@ -507,6 +529,9 @@ class MemLabConfig {
         this.puppeteerConfig.defaultViewport = null;
         this.defaultUserAgent = null;
     }
+    setRunInfo(key, value) {
+        this.extraRunInfoMap.set(key, value);
+    }
     removeFromSet(set, list) {
         for (const v of list) {
             set.delete(v);

package/dist/lib/Constant.js

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

package/dist/lib/FileManager.d.ts

@@ -10,6 +10,8 @@
 import type { MemLabConfig } from './Config';
 import type { AnyValue, FileOption } from './Types';
 /** @internal */
+export declare function joinAndProcessDir(options: FileOption, ...args: AnyValue[]): string;
+/** @internal */
 export declare class FileManager {
     private memlabConfigCache;
     getDefaultWorkDir(): string;
@@ -75,6 +77,7 @@ export declare class FileManager {
     rmWorkDir(options?: FileOption): void;
     isWithinInternalDirectory(filePath: string): boolean;
     createDefaultVisitOrderMetaFile(options?: FileOption): void;
+    createDefaultVisitOrderMetaFileWithSingleSnapshot(options: FileOption | undefined, snapshotFile: string): void;
     initDirs(config: MemLabConfig, options?: FileOption): void;
 }
 declare const _default: FileManager;

package/dist/lib/FileManager.js

@@ -12,13 +12,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FileManager = void 0;
+exports.FileManager = exports.joinAndProcessDir = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const Console_1 = __importDefault(require("./Console"));
 const Constant_1 = __importDefault(require("./Constant"));
 const Utils_1 = __importDefault(require("./Utils"));
+/** @internal */
 function joinAndProcessDir(options, ...args) {
     const filepath = path_1.default.join(...args);
     if (!fs_extra_1.default.existsSync(filepath)) {
@@ -34,6 +35,7 @@ function joinAndProcessDir(options, ...args) {
     }
     return filepath;
 }
+exports.joinAndProcessDir = joinAndProcessDir;
 /** @internal */
 class FileManager {
     constructor() {
@@ -310,6 +312,9 @@ class FileManager {
         }
     }
     isDirectory(file) {
+        if (!fs_extra_1.default.existsSync(file)) {
+            return false;
+        }
         const stats = fs_extra_1.default.statSync(file);
         return stats.isDirectory();
     }
@@ -356,6 +361,10 @@ class FileManager {
         }
         // If there is at least one snapshot, create a snap-seq.json file.
         // First, get the meta file for leak detection in a single heap snapshot
+        this.createDefaultVisitOrderMetaFileWithSingleSnapshot(options, snapshotFile);
+    }
+    createDefaultVisitOrderMetaFileWithSingleSnapshot(options = FileManager.defaultFileOption, snapshotFile) {
+        const snapshotSeqMetaFile = this.getSnapshotSequenceMetaFile(options);
         const codeDataDir = this.getCodeDataDir();
         const singleSnapshotMetaFile = path_1.default.join(codeDataDir, 'visit-order-single-snapshot.json');
         const visitOrder = JSON.parse(fs_extra_1.default.readFileSync(singleSnapshotMetaFile, 'UTF-8'));

package/dist/lib/HeapAnalyzer.d.ts

@@ -16,6 +16,10 @@ declare type DiffSnapshotsOptions = {
 declare type WorkDirOptions = {
     workDir?: string;
 };
+declare type GetTraceOptions = {
+    workDir?: string;
+    printConsoleOnly?: boolean;
+};
 declare class MemoryAnalyst {
     checkLeak(): Promise<ISerializedInfo[]>;
     diffLeakByWorkDir(options: DiffLeakOptions): Promise<ISerializedInfo[]>;
@@ -50,7 +54,7 @@ declare class MemoryAnalyst {
     serializeClusterUpdate(clusters: TraceCluster[], options?: {
         reclusterOnly?: boolean;
     }): Promise<void>;
-    dumpPathByNodeId(leakedIdSet: HeapNodeIdSet, snapshot: IHeapSnapshot, nodeIdsInSnapshots: Array<HeapNodeIdSet>, id: number, pathLoaderFile: string, summaryFile: string, options?: WorkDirOptions): void;
+    dumpPathByNodeId(leakedIdSet: HeapNodeIdSet, snapshot: IHeapSnapshot, nodeIdsInSnapshots: Array<HeapNodeIdSet>, id: number, pathLoaderFile: string, summaryFile: string, options?: GetTraceOptions): void;
 }
 declare const _default: MemoryAnalyst;
 export default _default;

package/dist/lib/HeapAnalyzer.js

@@ -34,6 +34,8 @@ const TraceFinder_1 = __importDefault(require("../paths/TraceFinder"));
 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* () {
@@ -44,14 +46,14 @@ class MemoryAnalyst {
     }
     diffLeakByWorkDir(options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const controlSnapshotDir = FileManager_1.default.getCurDataDir({
-                workDir: options.controlWorkDir,
-            });
+            const controlSnapshotDirs = options.controlWorkDirs.map(controlWorkDir => FileManager_1.default.getCurDataDir({
+                workDir: controlWorkDir,
+            }));
             const treatmentSnapshotDir = FileManager_1.default.getCurDataDir({
                 workDir: options.treatmentWorkDir,
             });
             // check control working dir
-            Utils_1.default.checkSnapshots({ snapshotDir: controlSnapshotDir });
+            controlSnapshotDirs.forEach(controlSnapshotDir => Utils_1.default.checkSnapshots({ snapshotDir: controlSnapshotDir }));
             // check treatment working dir
             Utils_1.default.checkSnapshots({ snapshotDir: treatmentSnapshotDir });
             // display control and treatment memory
@@ -63,31 +65,37 @@ class MemoryAnalyst {
     diffMemoryLeakTraces(options) {
         return __awaiter(this, void 0, void 0, function* () {
             Config_1.default.dumpNodeInfo = false;
-            // diff snapshots and get control raw paths
-            let snapshotDiff = yield this.diffSnapshots({
-                loadAllSnapshots: true,
-                workDir: options.controlWorkDir,
-            });
-            const controlLeakPaths = this.filterLeakPaths(snapshotDiff.leakedHeapNodeIdSet, snapshotDiff.snapshot, { workDir: options.controlWorkDir });
-            const controlSnapshot = snapshotDiff.snapshot;
+            // diff snapshots from control dirs and get control raw paths array
+            const controlSnapshots = [];
+            const leakPathsFromControlRuns = [];
+            for (const controlWorkDir of options.controlWorkDirs) {
+                const snapshotDiff = yield this.diffSnapshots({
+                    loadAllSnapshots: true,
+                    workDir: controlWorkDir,
+                });
+                leakPathsFromControlRuns.push(this.filterLeakPaths(snapshotDiff.leakedHeapNodeIdSet, snapshotDiff.snapshot, { workDir: controlWorkDir }));
+                controlSnapshots.push(snapshotDiff.snapshot);
+            }
             // diff snapshots and get treatment raw paths
-            snapshotDiff = yield this.diffSnapshots({
+            const snapshotDiff = yield this.diffSnapshots({
                 loadAllSnapshots: true,
                 workDir: options.treatmentWorkDir,
             });
-            const treatmentLeakPaths = this.filterLeakPaths(snapshotDiff.leakedHeapNodeIdSet, snapshotDiff.snapshot, { workDir: options.controlWorkDir });
+            const treatmentLeakPaths = this.filterLeakPaths(snapshotDiff.leakedHeapNodeIdSet, snapshotDiff.snapshot, { workDir: options.treatmentWorkDir });
             const treatmentSnapshot = snapshotDiff.snapshot;
-            Console_1.default.topLevel(`${controlLeakPaths.length} traces from control group`);
+            const controlPathCounts = JSON.stringify(leakPathsFromControlRuns.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(controlLeakPaths, controlSnapshot, treatmentLeakPaths, treatmentSnapshot, Utils_1.default.aggregateDominatorMetrics, {
+            const result = TraceBucket_1.default.clusterControlTreatmentPaths(leakPathsFromControlRuns, controlSnapshots, treatmentLeakPaths, treatmentSnapshot, Utils_1.default.aggregateDominatorMetrics, {
                 strategy: Config_1.default.isMLClustering
                     ? new MLTraceSimilarityStrategy_1.default()
                     : undefined,
             });
             Console_1.default.midLevel(`MemLab found ${result.treatmentOnlyClusters.length} new leak(s) in the treatment group`);
             yield this.serializeClusterUpdate(result.treatmentOnlyClusters);
-            // TODO (lgong): log leak traces
-            return [];
+            // 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);
         });
     }
     // find all unique pattern of leaks
@@ -124,7 +132,7 @@ class MemoryAnalyst {
                 snapshotLeakedHeapNodeIdSet = snapshotDiff.leakedHeapNodeIdSet;
                 snapshot = snapshotDiff.snapshot;
             }
-            this.dumpPathByNodeId(snapshotLeakedHeapNodeIdSet, snapshot, nodeIdsInSnapshots, Config_1.default.focusFiberNodeId, Config_1.default.viewJsonFile, Config_1.default.singleReportSummary);
+            this.dumpPathByNodeId(snapshotLeakedHeapNodeIdSet, snapshot, nodeIdsInSnapshots, Config_1.default.focusFiberNodeId, Config_1.default.viewJsonFile, Config_1.default.singleReportSummary, { printConsoleOnly: true });
         });
     }
     shouldLoadCompleteSnapshot(tabsOrder, tab) {
@@ -348,26 +356,37 @@ class MemoryAnalyst {
         this.printHeapAndLeakInfo(leakedNodeIds, snapshot, options);
         // get all leaked objects
         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 || !Utils_1.default.isInterestingPath(p)) {
+            if (p == null ||
+                !leakTraceFilter.filter(p, { config: Config_1.default, leakedNodeIds, snapshot })) {
+                return;
+            }
+            // 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;
             }
-            ++numOfLeakedObjects;
-            paths.push(p);
-            this.logLeakTraceSummary(p, nodeIdInPaths, snapshot, options);
+            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;
     }
@@ -401,11 +420,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);
@@ -451,10 +470,13 @@ class MemoryAnalyst {
                 return;
             }
             LeakTraceDetailsLogger_1.default.logTrace(leakedIdSet, snapshot, nodeIdsInSnapshots, path, pathLoaderFile);
-            const tabsOrder = Utils_1.default.loadTabsOrder(FileManager_1.default.getSnapshotSequenceMetaFile(options));
-            const interactionSummary = Serializer_1.default.summarizeTabsOrder(tabsOrder);
             let pathSummary = Serializer_1.default.summarizePath(path, nodeIdInPaths, snapshot, { color: true });
             Console_1.default.topLevel(pathSummary);
+            if (options.printConsoleOnly) {
+                return;
+            }
+            const tabsOrder = Utils_1.default.loadTabsOrder(FileManager_1.default.getSnapshotSequenceMetaFile(options));
+            const interactionSummary = Serializer_1.default.summarizeTabsOrder(tabsOrder);
             pathSummary = Serializer_1.default.summarizePath(path, nodeIdInPaths, snapshot);
             const summary = `Page Interaction: \n${interactionSummary}\n\n` +
                 `Path from GC Root to Leaked Object:\n${pathSummary}`;

package/dist/lib/RunInfoUtils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { Nullable, Optional, RunMetaInfo } from './Types';
+export declare class RunMetaInfoManager {
+    getRunMetaFilePath(options?: {
+        workDir?: Optional<string>;
+    }): string;
+    saveRunMetaInfo(runMetaInfo: RunMetaInfo, options?: {
+        workDir?: Optional<string>;
+        extraRunInfo?: Map<string, string>;
+    }): string;
+    private loadRunMetaInfoFromFile;
+    loadRunMetaInfo(options?: {
+        metaFile?: Optional<string>;
+        workDir?: Optional<string>;
+    }): RunMetaInfo;
+    loadRunMetaInfoSilentFail(options?: {
+        metaFile?: Optional<string>;
+        workDir?: Optional<string>;
+    }): Nullable<RunMetaInfo>;
+    loadRunMetaExternalTemplate(): RunMetaInfo;
+    setConfigFromRunMeta(options?: {
+        workDir?: Optional<string>;
+        silentFail?: boolean;
+    }): void;
+}
+declare const runInfoUtils: {
+    runMetaInfoManager: RunMetaInfoManager;
+};
+/** @internal */
+export default runInfoUtils;
+//# sourceMappingURL=RunInfoUtils.d.ts.map

package/dist/lib/RunInfoUtils.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RunMetaInfoManager = void 0;
+const fs_1 = __importDefault(require("fs"));
+const BrowserInfo_1 = __importDefault(require("./BrowserInfo"));
+const Config_1 = __importDefault(require("./Config"));
+const Constant_1 = __importDefault(require("./Constant"));
+const FileManager_1 = __importDefault(require("./FileManager"));
+const Utils_1 = __importDefault(require("./Utils"));
+const InternalValueSetter_1 = require("./InternalValueSetter");
+class RunMetaInfoManager {
+    getRunMetaFilePath(options) {
+        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 (Config_1.default.runMetaFile != null) {
+            return Config_1.default.runMetaFile;
+        }
+        return FileManager_1.default.getRunMetaFile();
+    }
+    saveRunMetaInfo(runMetaInfo, options) {
+        var _a;
+        const runMetaFile = this.getRunMetaFilePath(options);
+        const serializable = Object.assign(Object.assign({}, runMetaInfo), { extraInfo: Object.assign(Object.assign({}, Utils_1.default.mapToObject(Config_1.default.extraRunInfoMap)), Utils_1.default.mapToObject((_a = options === null || options === void 0 ? void 0 : options.extraRunInfo) !== null && _a !== void 0 ? _a : new Map())) });
+        fs_1.default.writeFileSync(runMetaFile, JSON.stringify(serializable, null, 2), 'UTF-8');
+        return runMetaFile;
+    }
+    loadRunMetaInfoFromFile(file) {
+        const content = fs_1.default.readFileSync(file, 'UTF-8');
+        const runMetaInfo = JSON.parse(content);
+        if (runMetaInfo && runMetaInfo.extraInfo) {
+            Config_1.default.extraRunInfoMap = Utils_1.default.objectToMap(runMetaInfo.extraInfo);
+        }
+        return runMetaInfo;
+    }
+    loadRunMetaInfo(options) {
+        const file = (options === null || options === void 0 ? void 0 : options.metaFile) || this.getRunMetaFilePath(options);
+        try {
+            return this.loadRunMetaInfoFromFile(file);
+        }
+        catch (_) {
+            throw Utils_1.default.haltOrThrow('Run info missing. Please make sure `memlab run` is complete.');
+        }
+    }
+    loadRunMetaInfoSilentFail(options) {
+        const file = (options === null || options === void 0 ? void 0 : options.metaFile) || this.getRunMetaFilePath(options);
+        try {
+            return this.loadRunMetaInfoFromFile(file);
+        }
+        catch (_) {
+            return null;
+        }
+    }
+    loadRunMetaExternalTemplate() {
+        const runMetaTemplateFile = FileManager_1.default.getRunMetaExternalTemplateFile();
+        return JSON.parse(fs_1.default.readFileSync(runMetaTemplateFile, 'UTF-8'));
+    }
+    setConfigFromRunMeta(options = {}) {
+        const meta = (options === null || options === void 0 ? void 0 : options.silentFail)
+            ? this.loadRunMetaInfoSilentFail(options)
+            : this.loadRunMetaInfo(options);
+        if (meta == null) {
+            return;
+        }
+        if ((meta === null || meta === void 0 ? void 0 : meta.app) == null || (meta === null || meta === void 0 ? void 0 : meta.interaction) == null) {
+            if (options === null || options === void 0 ? void 0 : options.silentFail) {
+                return;
+            }
+            throw Utils_1.default.haltOrThrow('No app or interaction infomation');
+        }
+        Config_1.default.targetApp = meta.app;
+        Config_1.default.targetTab = meta.interaction;
+        BrowserInfo_1.default.load(meta.browserInfo);
+    }
+}
+exports.RunMetaInfoManager = RunMetaInfoManager;
+const runInfoUtils = { runMetaInfoManager: new RunMetaInfoManager() };
+(0, InternalValueSetter_1.setInternalValue)(runInfoUtils, __filename, Constant_1.default.internalDir);
+/** @internal */
+exports.default = runInfoUtils;

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;