meminsight-test-demo 1.0.0

package/packages/core/src/analyzer/ArkStatAnalyzer.ts

@@ -0,0 +1,191 @@
+import * as fs from 'fs';
+import { IHeapSnapshot, IHeapNode, LeakTracePathItem } from "@memlab/core";
+import { ArkAnalyzer } from "./ArkAnalyzer";
+import { Loader } from "../utils/Loader";
+import { Finder } from '../utils/Finder';
+import { Log, ILoggable } from "../utils/Log";
+import { ArkStatCfg } from './ArkStatCfg';
+import { ArkNodesMap, ArkTracePathItem } from './ArkTracePath';
+
+/**
+ * Ark Heapsnapshot 统计分析器
+ */
+export class ArkStatAnalyzer extends ArkAnalyzer implements ILoggable {
+    public readonly DOMAIN = 'meminsight';
+    public readonly TAG = ArkStatAnalyzer.name;
+    public static readonly NAME = 'ark-stat-analyzer';
+    public static readonly DESC = "Analyze single heapsnapshot file and show statistics.";
+
+    protected snapshot: IHeapSnapshot;
+    protected snapshotFilePath: string;
+
+    constructor() {
+        super();
+        this.type = 'ark-stat-analyzer';
+    }
+
+    public override async analyze(args: any[]) : Promise<any> {
+        if (args.length < 1) {
+            Log.errorX(this, 'Argument count is not enough.');
+            return undefined;
+        }
+        this.snapshotFilePath = args[0] as string;
+        if (!fs.existsSync(this.snapshotFilePath)) {
+            Log.errorX(this, `File not found, ${this.snapshotFilePath}`);
+            return undefined;
+        }
+        this.snapshot = await Loader.loadFromFile(this.snapshotFilePath);
+        return this.snapshot;
+    }
+
+    /**
+     * get snapshot file path
+     * @returns snapshot file path
+     */
+    public getSnapshotFilePath() : string {
+        return this.snapshotFilePath;
+    }
+
+    public async getGCRoots() : Promise<Array<IHeapNode>> {
+        if (!this.snapshot) {
+            Log.errorX(this, 'Heapsnapshot has not been loaded.');
+            return [];
+        }     
+        return Finder.findGCRoots(this.snapshot);
+    }
+
+    public async getDetachedNodes() : Promise<Array<IHeapNode>> {
+        if (!this.snapshot) {
+            Log.errorX(this, 'Heapsnapshot has not been loaded.');
+            return [];
+        }
+        return Finder.findDetachedNodes(this.snapshot);
+    }
+    
+    public async getNodesByFilterCondition(
+        filter: (condition: any) => boolean, 
+        condition: any) : Promise<Array<IHeapNode>> {
+        if (!this.snapshot) {
+            Log.errorX(this, 'Heapsnapshot has not been loaded.');
+            return [];
+        }
+        const result = new Array<IHeapNode>();
+        this.snapshot.nodes.forEach((node, ) => {
+            if (filter(condition)) {
+                result.push(node);
+            }
+        });
+        return result;
+    }
+
+    public async getNodesByConfig() : Promise<Array<IHeapNode>> {
+        if (!this.snapshot) {
+            Log.errorX(this, 'Heapsnapshot has not been loaded.');
+            return [];
+        }
+        const result = new Array<IHeapNode>();
+        let cfg = this.configuration as ArkStatCfg;
+        if (cfg) {
+            this.snapshot.nodes.forEach((node, ) => {
+                if (!((cfg.Node.enableTypeWhiteList && !cfg.Node.typeWhiteList.includes(node.type))
+                    || (cfg.Node.enableTypeBlackList && cfg.Node.typeBlackList.includes(node.type))
+                    || (cfg.Node.enableNameWhiteList && !cfg.Node.nameWhiteList.includes(node.name))
+                    || (cfg.Node.enableNameBlackList && cfg.Node.nameBlackList.includes(node.name)))) {
+                    result.push(node);
+                }
+            });
+        } else {
+            Log.errorX(this, 'No analyzer configuration found.');
+        }
+        return result;
+    }
+
+    /**
+     * 获取指定节点的最短引用路径
+     * @param nodeId node id
+     * @returns 最短引用路径
+     */
+    public async getShortestPathToNode(nodeId: number) : Promise<ArkTracePathItem | undefined> {
+        if (!this.snapshot) {
+            Log.errorX(this, 'Heapsnapshot has not been loaded.');
+            return undefined;
+        }
+        const node = this.snapshot.nodes.get(nodeId);
+        if (!node) {
+            Log.errorX(this, `Node(${nodeId}) does not exist.`);
+            return undefined;
+        }
+        return Finder.findShortestPathToGCRoot(this.snapshot, node);
+    }
+
+    /**
+     * 根据配置参数获取符合条件的节点信息
+     * @param nameWhiteList class name 白名单
+     * @param typeWhiteList node type 白名单
+     * @param enableShortestPath 是否生成最短路径
+     * @param enableAggrationPath 是否生成聚合路径，enableShortestPath 为 true 时有效
+     * @param maxAggrationLength 最大聚合路径的个数，enableShortestPath 为 true 时有效
+     * @param enableMinRetainedSize 是否按最小retained size过滤，enableShortestPath 为 true 时有效
+     * @param minRetainedSize 最小retained size，enableShortestPath 为 true 时有效
+     * @param descending 聚合路径是否自上而下排序，enableShortestPath 为 true 时有效
+     * @returns 节点路径信息，可以按节点名、节点类型、节点到GC Roots的最短路径等信息过滤
+     */
+    public async getArkNodesMap(
+        nameWhiteList: string[],
+        typeWhiteList: string[] = ['object'], 
+        enableShortestPath: boolean = true,
+        enableAggrationPath: boolean = true,
+        maxAggrationLength = 3,
+        enableMinRetainedSize = false,
+        minRetainedSize = 1024 * 1024,
+        descending: boolean = true): Promise<ArkNodesMap | undefined> { 
+        if (!this.snapshot) {
+            Log.errorX(this, 'Heapsnapshot has not been loaded.');
+            return undefined;
+        }
+        const result = new ArkNodesMap();
+        this.snapshot.nodes.forEach((node, ) => {
+            result.addNode(this.snapshot, node, nameWhiteList, typeWhiteList, enableShortestPath);
+        });
+        if (enableShortestPath && enableAggrationPath) {
+            for (const [key, value] of result) {
+                value.getAggrationPathIndexes(
+                    descending, 
+                    maxAggrationLength, 
+                    enableMinRetainedSize ? minRetainedSize : -1);
+            }
+        }
+        return result;
+    }
+
+    /**
+     * 根据配置获取符合条件的节点信息
+     * 配置通过 setConfig(cfg: any) 设置，默认配置参见 ArkStatCfg.defaultArkStatCfg()
+     */
+    public async getArkNodesMapByConfig() : Promise<ArkNodesMap | undefined> {
+        let cfg = this.configuration as ArkStatCfg;
+        if (!cfg) {
+            Log.errorX(this, 'No analyzer configuration found.');
+            return undefined;
+        }
+        let nameWhiteList = cfg.Node.nameWhiteList;
+        let typeWhiteList = cfg.Node.typeWhiteList;
+        let enableShortestPath = cfg.Path.enableShortest;
+        let enableAggrationPath = cfg.Path.enableAggration;
+        let maxAggrationLength = cfg.Path.aggrationLength;
+        let enableMinRetainedSize = cfg.Path.enableMinRetainedSize;      
+        let minRetainedSize = cfg.Path.minRetainedSize;
+        let descending = cfg.Path.aggrationDescending;
+        return this.getArkNodesMap(nameWhiteList, typeWhiteList, 
+            enableShortestPath, enableAggrationPath, maxAggrationLength,
+            enableMinRetainedSize, minRetainedSize, descending);
+    }
+
+     /**
+     * 获取所有共享对象，Map 以对象tag作为 key，相同tag的对象作为 value
+     * @returns Map<string, Array<IHeapNode>>
+     */
+    public async getSharedHeapNodesMap() : Promise<Map<string, Array<IHeapNode>>> {
+        return Finder.getSharedHeapNodesMap(this.snapshot);
+    }
+}

package/packages/core/src/analyzer/ArkStatCfg.ts

@@ -0,0 +1,77 @@
+/**
+ * Ark Statistics Configuration
+ */
+export type ArkStatCfg = {
+    Node: {
+        enableTypeWhiteList: boolean,
+        typeWhiteList: string[],
+        enableTypeBlackList: boolean,
+        typeBlackList: string[],
+        enableNameWhiteList: boolean,
+        nameWhiteList: string[],
+        enableNameBlackList: boolean,
+        nameBlackList: string[],
+        enableId: boolean,
+        enableType: boolean,
+        enableName: boolean,
+        enableSelfSize: boolean,
+        enableRetainedSize: boolean,
+    },
+    Path: {
+        enableDistance: boolean,
+        enableSelfSize: boolean,
+        enableRetainedSize: boolean,
+        enableNativeSize: boolean,
+        enableShortest: boolean,
+        enableShortestLength: boolean,
+        shortestLength: number,
+        enableAggration: boolean,
+        aggrationLength: number,
+        aggrationDescending: boolean,
+        enableMinRetainedSize: boolean,
+        minRetainedSize: number,
+        enableMaxRetainedSize: boolean,
+        maxRetainedSize: number,
+    }
+}
+
+/**
+ * Ark Statistics default configuration
+ * @returns default configuration
+ */
+export function defaultArkStatCfg() : ArkStatCfg {
+    return {
+        Node: {
+            enableTypeWhiteList: true,
+            typeWhiteList: ["object", "closure", "string", "array"],
+            enableTypeBlackList: false,
+            typeBlackList: [],
+            enableNameWhiteList: false,
+            nameWhiteList: [],
+            enableNameBlackList: false,
+            nameBlackList: [],
+            enableId: true,
+            enableType: true,
+            enableName: true,
+            enableSelfSize: false,
+            enableRetainedSize: false,
+        },
+        Path: {
+            enableDistance: true,
+            enableSelfSize: true,
+            enableRetainedSize: true,
+            enableNativeSize: false,
+            enableShortest: true,
+            enableShortestLength: false,
+            shortestLength: 0,
+            enableAggration: true,
+            aggrationLength: 3,
+            aggrationDescending: true,
+            enableMinRetainedSize: true,
+            minRetainedSize: 1024 * 1024,  // 1MB
+            enableMaxRetainedSize: false,
+            maxRetainedSize: 0,
+        },
+
+    }
+}

package/packages/core/src/analyzer/ArkTracePath.ts

@@ -0,0 +1,269 @@
+import { IHeapSnapshot, IHeapNode, LeakTracePathItem } from '@memlab/core'
+import { Finder } from '../utils/Finder';
+import { ILoggable, Log } from '../utils/Log';
+
+/**
+ * ArkTracePathItem
+ */
+export type ArkTracePathItem = LeakTracePathItem;
+
+/**
+ * ArkNodeTracePath
+ */
+export class ArkNodeTracePath {
+    public readonly tracePathItem: ArkTracePathItem;
+    public readonly uid: string;
+    public readonly nodeIds: number[];
+    public readonly reverse: boolean;
+    public readonly retainedSize: number;
+
+    constructor(item: ArkTracePathItem, reverse: boolean = false) {
+        this.tracePathItem = item;
+        this.nodeIds = ArkNodeTracePath.getNodeIdTrace(item);
+        this.retainedSize = ArkNodeTracePath.getRetainedSize(item);
+        this.reverse = reverse;
+        this.uid = reverse ? this.nodeIds.reverse().join('<-') : this.nodeIds.join('->');
+    }
+
+    public getTracePathInfo(joinStr: string = '===>') : string {
+        if (this.nodeIds.length === 0) {
+            return '';
+        }
+        const snapshot = this.tracePathItem.node?.snapshot;
+        if (!snapshot) {
+            Log.error('meminsight', ArkNodeTracePath.name, 'Failed to get snapshot.');
+            return '';
+        }
+        const result: string[] = [];
+        this.nodeIds.forEach(id => {
+            let node = snapshot.getNodeById(id);
+            if (node) {
+                let sizeStr = node.retainedSize >= 1024 * 1024 ?
+                    (node.retainedSize / (1024 * 1024)).toFixed(2) + 'MB' :
+                    (node.retainedSize / 1024).toFixed(2) + 'KB';
+                result.push(`@${id} (${node.type}) [${sizeStr}] ${node.name}`)
+            } 
+        })
+        return result.join(`\n${joinStr}`);
+    }
+
+    public static getNodeIdTrace(item: ArkTracePathItem) : number[] {
+        const nodeIds: number[] = [];
+        let curItem : ArkTracePathItem | undefined = item;
+        while (curItem) {
+            let node: IHeapNode | undefined = curItem.node;
+            if (!node) {
+                break;
+            }
+            nodeIds.push(node.id);
+            curItem = curItem.next;
+        }
+        return nodeIds;
+    }
+
+    /**
+     * 获取本路径上的节点retained size
+     * @param item 
+     * @returns 
+     */
+    public static getRetainedSize(item: ArkTracePathItem) : number {
+        let retained: number = 0;
+        let curItem : ArkTracePathItem | undefined = item;
+        while (curItem) {
+            let node: IHeapNode | undefined = curItem.node;
+            if (!node) {
+                break;
+            }
+            retained += node.self_size;
+            curItem = curItem.next;
+        }
+        return retained;
+    }
+}
+
+/**
+ * ArkNode最短路径uid和最短路径索引关系对象
+ */
+export class ArkNodePathIndexes {
+    public readonly uid: string;
+    public indexes: number[];
+
+    constructor(uid: string) {
+        this.uid = uid;
+    }
+
+    public addIndex(index: number) {
+        this.indexes.push(index);
+    }
+
+    public get(filter: (condition: any) => boolean, condition: any) {
+        return this.indexes.filter((index) => {
+            return filter(condition);
+        });
+    }
+}
+
+/**
+ * ArkNodes
+ */
+export class ArkNodes extends Array<number> implements ILoggable {
+    public readonly DOMAIN: string = 'meminsight';
+    public readonly TAG: string = ArkNodes.name;
+    public className: string = '';         // node class name
+    public selfSize: number = 0;           // node total self size
+    public retainedSize: number = 0;       // node total retained size
+    public shortestPaths: ArkNodeTracePath[]; // shortest path array of all node with same calss name
+    public aggrationPathIndexes: Map<string, ArkNodePathIndexes>;  // <path uid, path indexes>
+
+    /**
+     * ArkNodes constructor
+     * @param className node name
+     * @param selfSize node self size
+     * @param retainedSize node retained size
+     */
+    constructor(className: string, selfSize: number, retainedSize: number) {
+        super();
+        this.className = className;
+        this.selfSize = selfSize;
+        this.retainedSize = retainedSize;
+    }
+
+    /**
+     * add shortest node trace path
+     * @param path shortest node trace path
+     */
+    public addShortestPath(path: ArkNodeTracePath) : void {
+        this.shortestPaths.push(path);
+    }
+
+    /**
+     * add node id
+     * @param nodeId node id
+     */
+    public addNodeId(nodeId: number) : void {
+        this.push(nodeId);
+    }
+
+    /**
+     * 获取最短路径uid和最短路径索引和引用次数的映射数据
+     * uid = [...node.id].join('->')
+     * @param descending 按引用次数降序排序，否则升序排序
+     * @param maxIndexLength 最大引用路径个数
+     */
+    public getAggrationPathIndexes(descending: boolean = true, 
+        maxIndexLength: number = -1, minRetainedSize = -1) : void {
+        if (this.shortestPaths.length === 0) {
+            Log.warnX(this, 'No shortest path found');
+            return;
+        }
+        const indexes = new Map<string, ArkNodePathIndexes>();
+        this.shortestPaths.forEach((path, index) => {
+            const indexesItem = indexes.get(path.uid);
+            if (!indexesItem) {
+                const pathIndexes = new ArkNodePathIndexes(path.uid);
+                pathIndexes.addIndex(index);
+                indexes.set(path.uid, pathIndexes);
+            } else {
+                indexesItem.addIndex(index);
+            }
+        });
+        const sortedIndexes = descending 
+            ? new Map([...indexes.entries()].sort((a, b) => a[1].indexes.length - b[1].indexes.length))
+            : new Map([...indexes.entries()].sort((a, b) => b[1].indexes.length - a[1].indexes.length));
+        if ((maxIndexLength <= 0) || (sortedIndexes.size <= maxIndexLength)) {
+            this.aggrationPathIndexes = sortedIndexes;
+        } else {
+            this.aggrationPathIndexes = new Map([...sortedIndexes.entries()].slice(0, maxIndexLength));
+        }
+        if (minRetainedSize > 0) {
+            this.aggrationPathIndexes.forEach((pathIndexes, uid) => {
+                const tmpIndexes: number[] = [];
+                let idx = pathIndexes.indexes.pop();
+                while (idx) {
+                    let size = this.shortestPaths.at(idx)?.retainedSize || 0;
+                    if (size >= minRetainedSize) {
+                        tmpIndexes.push(idx);
+                    }
+                    idx = pathIndexes.indexes.pop();
+                }
+                pathIndexes.indexes = tmpIndexes;
+            });
+        }
+    }
+
+    public getPathIndexesRetainedSize(uid: string) : number {
+        let pathIndexes = this.aggrationPathIndexes.get(uid);
+        if (!pathIndexes) {
+            return 0;
+        }
+        let preSize = 0;
+        let curSize: number | undefined;
+        return pathIndexes.indexes.reduce((pre, cur) => {
+            curSize = this.shortestPaths.at(cur)?.retainedSize;
+            if (!curSize) {
+                return preSize;
+            }
+            preSize = curSize;
+            return preSize + curSize;
+        }, 0);
+    }
+}
+
+/**
+ * ArkNodes Map<nodeName, nodeId array>
+ */
+export class ArkNodesMap extends Map<string, ArkNodes> implements ILoggable {
+    DOMAIN: string = 'meminsight'
+    TAG: string = ArkNodesMap.name;
+
+    constructor() {
+        super();
+    }
+
+    /**
+     * add node to map
+     * @param snapshot heap snapshot
+     * @param node heap node
+     * @param nameWhiteList node names
+     * @param typeWhiteList node types
+     * @param enableShortestPath enable shortest path
+     */
+    public addNode(
+        snapshot: IHeapSnapshot,
+        node: IHeapNode,
+        nameWhiteList: string[],
+        typeWhiteList: string[] = ['object'],
+        enableShortestPath: boolean = true) : void {
+        // true if names is empty or types include node.type
+        if ((nameWhiteList.length == 0 
+            || nameWhiteList.includes(node.name)) 
+            && typeWhiteList.includes(node.type)) {
+            const arkNodes: ArkNodes | undefined = this.get(node.name);
+            if (!arkNodes) {
+                let arkNodes: ArkNodes = new ArkNodes(node.name, node.self_size, node.retainedSize);
+                if (enableShortestPath) {
+                    const arkTracePathItem: ArkTracePathItem | undefined = Finder.findShortestPathToGCRoot(snapshot, node);
+                    if (arkTracePathItem) {
+                        arkNodes.addShortestPath(new ArkNodeTracePath(arkTracePathItem));
+                    } else {
+                        Log.errorX(this, 'ArkNodesMap1: Finder.findShortestPathToGCRoot return undefined.');
+                    }
+                }
+                arkNodes.addNodeId(node.id);
+                this.set(node.name, arkNodes);
+            } else { 
+                arkNodes.selfSize += node.self_size;
+                arkNodes.retainedSize += node.retainedSize;
+                if (enableShortestPath) {
+                    const arkTracePathItem: ArkTracePathItem | undefined = Finder.findShortestPathToGCRoot(snapshot, node);
+                    if (arkTracePathItem) {
+                        arkNodes.addShortestPath(new ArkNodeTracePath(arkTracePathItem));
+                    } else {
+                        Log.errorX(this, 'ArkNodesMap2: Finder.findShortestPathToGCRoot return undefined.');
+                    }
+                }
+                arkNodes.addNodeId(node.id);
+            }
+        }
+    }
+}

package/packages/core/src/analyzer/ArkTracer.ts

@@ -0,0 +1,42 @@
+import { serializer } from "@memlab/core"
+import { ArkTracePathItem } from "./ArkTracePath";
+
+/**
+ * ArkTracePath Filter function
+ */
+export type ArkTracePathFilter = (condition?: any) => boolean;
+/**
+ * ArkTracePath Output function
+ */
+export type ArkTracePathOutput = (path: ArkTracePathItem, filter?: ArkTracePathFilter, condition?: any) => string;
+
+const defaultOutput: ArkTracePathOutput = (path: ArkTracePathItem) => {
+    let snapshot = path?.node?.snapshot;
+    return snapshot ? serializer.summarizePath(path, new Set<number>(), snapshot, {color: true}) : '';
+};
+
+/**
+ * ArkTracer
+ */
+export class ArkTracer {
+    public static outputTracePath(
+        tracePath: ArkTracePathItem, 
+        output?: ArkTracePathOutput, 
+        filter?: ArkTracePathFilter,
+        condition?: any) : void {
+        let result: string = output ? output(tracePath, filter, condition) : defaultOutput(tracePath);
+        if (result !== '') {
+            console.log(result);
+        } else {
+            console.log('No leak trace path.');
+        }
+    }
+
+    public static getTracePathString(
+        tracePath: ArkTracePathItem, 
+        output?: ArkTracePathOutput, 
+        filter?: ArkTracePathFilter, 
+        condition?: any) : string {
+        return output ? output(tracePath, filter, condition) : defaultOutput(tracePath);
+    } 
+}