@esengine/ecs-framework 2.2.21 → 2.3.0

package/bin/Utils/Profiler/ProfilerSDK.js

@@ -0,0 +1,727 @@
+/**
+ * 性能分析器 SDK
+ *
+ * 提供统一的性能分析接口，支持：
+ * - 手动采样标记
+ * - 自动作用域测量
+ * - 调用层级追踪
+ * - 计数器和仪表
+ */
+import { ProfileCategory, DEFAULT_PROFILER_CONFIG } from './ProfilerTypes';
+let idCounter = 0;
+function generateId() {
+    return `sample_${++idCounter}_${Date.now()}`;
+}
+/**
+ * 性能分析器 SDK
+ */
+export class ProfilerSDK {
+    constructor(config) {
+        this.currentFrame = null;
+        this.frameHistory = [];
+        this.frameNumber = 0;
+        this.activeSamples = new Map();
+        this.sampleStack = [];
+        this.counters = new Map();
+        this.callGraph = new Map();
+        this.gcCount = 0;
+        this.previousHeapSize = 0;
+        this.longTasks = [];
+        this.performanceObserver = null;
+        this.config = { ...DEFAULT_PROFILER_CONFIG, ...config };
+        if (this.config.detectLongTasks) {
+            this.setupLongTaskObserver();
+        }
+    }
+    /**
+     * 获取单例实例
+     */
+    static getInstance(config) {
+        if (!ProfilerSDK.instance) {
+            ProfilerSDK.instance = new ProfilerSDK(config);
+        }
+        return ProfilerSDK.instance;
+    }
+    /**
+     * 重置实例（测试用）
+     */
+    static resetInstance() {
+        if (ProfilerSDK.instance) {
+            ProfilerSDK.instance.dispose();
+            ProfilerSDK.instance = null;
+        }
+    }
+    /**
+     * 开始采样
+     */
+    static beginSample(name, category = ProfileCategory.Custom) {
+        return ProfilerSDK.getInstance().beginSample(name, category);
+    }
+    /**
+     * 结束采样
+     */
+    static endSample(handle) {
+        if (handle) {
+            ProfilerSDK.getInstance().endSample(handle);
+        }
+    }
+    /**
+     * 测量同步函数执行时间
+     */
+    static measure(name, fn, category = ProfileCategory.Custom) {
+        return ProfilerSDK.getInstance().measure(name, fn, category);
+    }
+    /**
+     * 测量异步函数执行时间
+     */
+    static async measureAsync(name, fn, category = ProfileCategory.Custom) {
+        return ProfilerSDK.getInstance().measureAsync(name, fn, category);
+    }
+    /**
+     * 开始帧
+     */
+    static beginFrame() {
+        ProfilerSDK.getInstance().beginFrame();
+    }
+    /**
+     * 结束帧
+     */
+    static endFrame() {
+        ProfilerSDK.getInstance().endFrame();
+    }
+    /**
+     * 递增计数器
+     */
+    static incrementCounter(name, value = 1, category = ProfileCategory.Custom) {
+        ProfilerSDK.getInstance().incrementCounter(name, value, category);
+    }
+    /**
+     * 设置仪表值
+     */
+    static setGauge(name, value, category = ProfileCategory.Custom) {
+        ProfilerSDK.getInstance().setGauge(name, value, category);
+    }
+    /**
+     * 启用/禁用分析器
+     */
+    static setEnabled(enabled) {
+        ProfilerSDK.getInstance().setEnabled(enabled);
+    }
+    /**
+     * 检查是否启用
+     */
+    static isEnabled() {
+        return ProfilerSDK.getInstance().config.enabled;
+    }
+    /**
+     * 获取当前帧数据
+     */
+    static getCurrentFrame() {
+        return ProfilerSDK.getInstance().currentFrame;
+    }
+    /**
+     * 获取帧历史
+     */
+    static getFrameHistory() {
+        return ProfilerSDK.getInstance().frameHistory;
+    }
+    /**
+     * 获取分析报告
+     */
+    static getReport(frameCount) {
+        return ProfilerSDK.getInstance().generateReport(frameCount);
+    }
+    /**
+     * 重置数据
+     */
+    static reset() {
+        ProfilerSDK.getInstance().reset();
+    }
+    /**
+     * 开始采样
+     */
+    beginSample(name, category = ProfileCategory.Custom) {
+        if (!this.config.enabled || !this.config.enabledCategories.has(category)) {
+            return null;
+        }
+        const parentHandle = this.sampleStack.length > 0
+            ? this.sampleStack[this.sampleStack.length - 1]
+            : undefined;
+        if (parentHandle && this.sampleStack.length >= this.config.maxSampleDepth) {
+            return null;
+        }
+        const handle = {
+            id: generateId(),
+            name,
+            category,
+            startTime: performance.now(),
+            depth: this.sampleStack.length,
+            parentId: parentHandle?.id
+        };
+        this.activeSamples.set(handle.id, handle);
+        this.sampleStack.push(handle);
+        return handle;
+    }
+    /**
+     * 结束采样
+     */
+    endSample(handle) {
+        if (!this.config.enabled || !this.activeSamples.has(handle.id)) {
+            return;
+        }
+        const endTime = performance.now();
+        const duration = endTime - handle.startTime;
+        // 获取父级 handle（在删除当前 handle 之前）
+        const parentHandle = handle.parentId ? this.activeSamples.get(handle.parentId) : undefined;
+        const sample = {
+            id: handle.id,
+            name: handle.name,
+            category: handle.category,
+            startTime: handle.startTime,
+            endTime,
+            duration,
+            selfTime: duration,
+            parentId: handle.parentId,
+            parentName: parentHandle?.name,
+            depth: handle.depth,
+            callCount: 1
+        };
+        if (this.currentFrame) {
+            this.currentFrame.samples.push(sample);
+        }
+        this.updateCallGraph(handle.name, handle.category, duration, parentHandle);
+        this.activeSamples.delete(handle.id);
+        const stackIndex = this.sampleStack.indexOf(handle);
+        if (stackIndex !== -1) {
+            this.sampleStack.splice(stackIndex, 1);
+        }
+    }
+    /**
+     * 测量同步函数
+     */
+    measure(name, fn, category = ProfileCategory.Custom) {
+        const handle = this.beginSample(name, category);
+        try {
+            return fn();
+        }
+        finally {
+            if (handle) {
+                this.endSample(handle);
+            }
+        }
+    }
+    /**
+     * 测量异步函数
+     */
+    async measureAsync(name, fn, category = ProfileCategory.Custom) {
+        const handle = this.beginSample(name, category);
+        try {
+            return await fn();
+        }
+        finally {
+            if (handle) {
+                this.endSample(handle);
+            }
+        }
+    }
+    /**
+     * 开始帧
+     */
+    beginFrame() {
+        if (!this.config.enabled)
+            return;
+        this.frameNumber++;
+        this.currentFrame = {
+            frameNumber: this.frameNumber,
+            startTime: performance.now(),
+            endTime: 0,
+            duration: 0,
+            samples: [],
+            sampleStats: [],
+            counters: new Map(this.counters),
+            memory: this.captureMemory(),
+            categoryStats: new Map()
+        };
+        this.resetFrameCounters();
+    }
+    /**
+     * 结束帧
+     */
+    endFrame() {
+        if (!this.config.enabled || !this.currentFrame)
+            return;
+        this.currentFrame.endTime = performance.now();
+        this.currentFrame.duration = this.currentFrame.endTime - this.currentFrame.startTime;
+        this.calculateSampleStats();
+        this.calculateCategoryStats();
+        this.frameHistory.push(this.currentFrame);
+        while (this.frameHistory.length > this.config.maxFrameHistory) {
+            this.frameHistory.shift();
+        }
+        this.sampleStack = [];
+        this.activeSamples.clear();
+    }
+    /**
+     * 递增计数器
+     */
+    incrementCounter(name, value = 1, category = ProfileCategory.Custom) {
+        if (!this.config.enabled)
+            return;
+        let counter = this.counters.get(name);
+        if (!counter) {
+            counter = {
+                name,
+                category,
+                value: 0,
+                type: 'counter',
+                history: []
+            };
+            this.counters.set(name, counter);
+        }
+        counter.value += value;
+        counter.history.push({ time: performance.now(), value: counter.value });
+        if (counter.history.length > 100) {
+            counter.history.shift();
+        }
+    }
+    /**
+     * 设置仪表值
+     */
+    setGauge(name, value, category = ProfileCategory.Custom) {
+        if (!this.config.enabled)
+            return;
+        let counter = this.counters.get(name);
+        if (!counter) {
+            counter = {
+                name,
+                category,
+                value: 0,
+                type: 'gauge',
+                history: []
+            };
+            this.counters.set(name, counter);
+        }
+        counter.value = value;
+        counter.history.push({ time: performance.now(), value });
+        if (counter.history.length > 100) {
+            counter.history.shift();
+        }
+    }
+    /**
+     * 设置启用状态
+     */
+    setEnabled(enabled) {
+        this.config.enabled = enabled;
+        if (enabled && this.config.detectLongTasks && !this.performanceObserver) {
+            this.setupLongTaskObserver();
+        }
+    }
+    /**
+     * 重置数据
+     */
+    reset() {
+        this.frameHistory = [];
+        this.currentFrame = null;
+        this.frameNumber = 0;
+        this.activeSamples.clear();
+        this.sampleStack = [];
+        this.counters.clear();
+        this.callGraph.clear();
+        this.gcCount = 0;
+        this.longTasks = [];
+    }
+    /**
+     * 生成分析报告
+     */
+    generateReport(frameCount) {
+        const frames = frameCount
+            ? this.frameHistory.slice(-frameCount)
+            : this.frameHistory;
+        if (frames.length === 0) {
+            return this.createEmptyReport();
+        }
+        const frameTimes = frames.map((f) => f.duration);
+        const sortedTimes = [...frameTimes].sort((a, b) => a - b);
+        const aggregatedStats = this.aggregateSampleStats(frames);
+        const hotspots = aggregatedStats
+            .sort((a, b) => b.inclusiveTime - a.inclusiveTime)
+            .slice(0, 20);
+        const categoryBreakdown = this.aggregateCategoryStats(frames);
+        // 根据帧历史重新计算 callGraph（不使用全局累积的数据）
+        const callGraph = this.buildCallGraphFromFrames(frames);
+        const firstFrame = frames[0];
+        const lastFrame = frames[frames.length - 1];
+        return {
+            startTime: firstFrame?.startTime ?? 0,
+            endTime: lastFrame?.endTime ?? 0,
+            totalFrames: frames.length,
+            averageFrameTime: frameTimes.reduce((a, b) => a + b, 0) / frameTimes.length,
+            minFrameTime: Math.min(...frameTimes),
+            maxFrameTime: Math.max(...frameTimes),
+            p95FrameTime: sortedTimes[Math.floor(sortedTimes.length * 0.95)] || 0,
+            p99FrameTime: sortedTimes[Math.floor(sortedTimes.length * 0.99)] || 0,
+            hotspots,
+            callGraph,
+            categoryBreakdown,
+            memoryTrend: frames.map((f) => f.memory),
+            longTasks: [...this.longTasks]
+        };
+    }
+    /**
+     * 从帧历史构建调用图
+     * 注意：totalTime 存储的是平均耗时（总耗时/调用次数），而不是累计总耗时
+     */
+    buildCallGraphFromFrames(frames) {
+        // 临时存储累计数据
+        const tempData = new Map();
+        for (const frame of frames) {
+            for (const sample of frame.samples) {
+                // 获取或创建当前函数的节点
+                let node = tempData.get(sample.name);
+                if (!node) {
+                    node = {
+                        category: sample.category,
+                        callCount: 0,
+                        totalTime: 0,
+                        callers: new Map(),
+                        callees: new Map()
+                    };
+                    tempData.set(sample.name, node);
+                }
+                node.callCount++;
+                node.totalTime += sample.duration;
+                // 如果有父级，建立调用关系
+                if (sample.parentName) {
+                    // 记录当前函数被谁调用
+                    const callerData = node.callers.get(sample.parentName) || { count: 0, totalTime: 0 };
+                    callerData.count++;
+                    callerData.totalTime += sample.duration;
+                    node.callers.set(sample.parentName, callerData);
+                    // 确保父节点存在并记录它调用了谁
+                    let parentNode = tempData.get(sample.parentName);
+                    if (!parentNode) {
+                        parentNode = {
+                            category: sample.category,
+                            callCount: 0,
+                            totalTime: 0,
+                            callers: new Map(),
+                            callees: new Map()
+                        };
+                        tempData.set(sample.parentName, parentNode);
+                    }
+                    const calleeData = parentNode.callees.get(sample.name) || { count: 0, totalTime: 0 };
+                    calleeData.count++;
+                    calleeData.totalTime += sample.duration;
+                    parentNode.callees.set(sample.name, calleeData);
+                }
+            }
+        }
+        // 转换为最终结果，将 totalTime 改为平均耗时
+        const callGraph = new Map();
+        for (const [name, data] of tempData) {
+            const avgCallers = new Map();
+            for (const [callerName, callerData] of data.callers) {
+                avgCallers.set(callerName, {
+                    count: callerData.count,
+                    totalTime: callerData.count > 0 ? callerData.totalTime / callerData.count : 0
+                });
+            }
+            const avgCallees = new Map();
+            for (const [calleeName, calleeData] of data.callees) {
+                avgCallees.set(calleeName, {
+                    count: calleeData.count,
+                    totalTime: calleeData.count > 0 ? calleeData.totalTime / calleeData.count : 0
+                });
+            }
+            callGraph.set(name, {
+                name,
+                category: data.category,
+                callCount: data.callCount,
+                totalTime: data.callCount > 0 ? data.totalTime / data.callCount : 0,
+                callers: avgCallers,
+                callees: avgCallees
+            });
+        }
+        return callGraph;
+    }
+    /**
+     * 获取调用图数据
+     */
+    getCallGraph() {
+        return new Map(this.callGraph);
+    }
+    /**
+     * 获取特定函数的调用关系
+     */
+    getFunctionCallInfo(name) {
+        const node = this.callGraph.get(name);
+        if (!node)
+            return null;
+        return {
+            callers: Array.from(node.callers.entries()).map(([name, data]) => ({
+                name,
+                ...data
+            })),
+            callees: Array.from(node.callees.entries()).map(([name, data]) => ({
+                name,
+                ...data
+            }))
+        };
+    }
+    /**
+     * 释放资源
+     */
+    dispose() {
+        if (this.performanceObserver) {
+            this.performanceObserver.disconnect();
+            this.performanceObserver = null;
+        }
+        this.reset();
+    }
+    captureMemory() {
+        const now = performance.now();
+        let usedHeapSize = 0;
+        let totalHeapSize = 0;
+        let heapSizeLimit = 0;
+        const perfWithMemory = performance;
+        if (perfWithMemory.memory) {
+            usedHeapSize = perfWithMemory.memory.usedJSHeapSize || 0;
+            totalHeapSize = perfWithMemory.memory.totalJSHeapSize || 0;
+            heapSizeLimit = perfWithMemory.memory.jsHeapSizeLimit || 0;
+            if (this.previousHeapSize > 0 && usedHeapSize < this.previousHeapSize - 1024 * 1024) {
+                this.gcCount++;
+            }
+            this.previousHeapSize = usedHeapSize;
+        }
+        return {
+            timestamp: now,
+            usedHeapSize,
+            totalHeapSize,
+            heapSizeLimit,
+            utilizationPercent: heapSizeLimit > 0 ? (usedHeapSize / heapSizeLimit) * 100 : 0,
+            gcCount: this.gcCount
+        };
+    }
+    resetFrameCounters() {
+        for (const counter of this.counters.values()) {
+            if (counter.type === 'counter') {
+                counter.value = 0;
+            }
+        }
+    }
+    calculateSampleStats() {
+        if (!this.currentFrame)
+            return;
+        const sampleMap = new Map();
+        for (const sample of this.currentFrame.samples) {
+            let stats = sampleMap.get(sample.name);
+            if (!stats) {
+                stats = {
+                    name: sample.name,
+                    category: sample.category,
+                    inclusiveTime: 0,
+                    exclusiveTime: 0,
+                    callCount: 0,
+                    averageTime: 0,
+                    minTime: Number.MAX_VALUE,
+                    maxTime: 0,
+                    percentOfFrame: 0,
+                    percentOfParent: 0,
+                    children: [],
+                    depth: sample.depth
+                };
+                sampleMap.set(sample.name, stats);
+            }
+            stats.inclusiveTime += sample.duration;
+            stats.callCount += 1;
+            stats.minTime = Math.min(stats.minTime, sample.duration);
+            stats.maxTime = Math.max(stats.maxTime, sample.duration);
+        }
+        for (const sample of this.currentFrame.samples) {
+            if (sample.parentId) {
+                const parentSample = this.currentFrame.samples.find((s) => s.id === sample.parentId);
+                if (parentSample) {
+                    const parentStats = sampleMap.get(parentSample.name);
+                    if (parentStats) {
+                        parentStats.exclusiveTime = parentStats.inclusiveTime;
+                        for (const childSample of this.currentFrame.samples) {
+                            if (childSample.parentId === parentSample.id) {
+                                parentStats.exclusiveTime -= childSample.duration;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        const frameDuration = this.currentFrame.duration || 1;
+        for (const stats of sampleMap.values()) {
+            stats.averageTime = stats.inclusiveTime / stats.callCount;
+            stats.percentOfFrame = (stats.inclusiveTime / frameDuration) * 100;
+            if (stats.exclusiveTime === 0) {
+                stats.exclusiveTime = stats.inclusiveTime;
+            }
+        }
+        this.currentFrame.sampleStats = Array.from(sampleMap.values())
+            .sort((a, b) => b.inclusiveTime - a.inclusiveTime);
+    }
+    calculateCategoryStats() {
+        if (!this.currentFrame)
+            return;
+        const categoryMap = new Map();
+        for (const sample of this.currentFrame.samples) {
+            if (sample.depth === 0) {
+                let stats = categoryMap.get(sample.category);
+                if (!stats) {
+                    stats = { totalTime: 0, sampleCount: 0 };
+                    categoryMap.set(sample.category, stats);
+                }
+                stats.totalTime += sample.duration;
+                stats.sampleCount += 1;
+            }
+        }
+        const frameDuration = this.currentFrame.duration || 1;
+        for (const [category, stats] of categoryMap) {
+            this.currentFrame.categoryStats.set(category, {
+                ...stats,
+                percentOfFrame: (stats.totalTime / frameDuration) * 100
+            });
+        }
+    }
+    updateCallGraph(name, category, duration, parentHandle) {
+        let node = this.callGraph.get(name);
+        if (!node) {
+            node = {
+                name,
+                category,
+                callCount: 0,
+                totalTime: 0,
+                callers: new Map(),
+                callees: new Map()
+            };
+            this.callGraph.set(name, node);
+        }
+        node.callCount++;
+        node.totalTime += duration;
+        // 如果有父级，建立调用关系
+        if (parentHandle) {
+            // 记录当前函数被谁调用
+            const callerData = node.callers.get(parentHandle.name) || { count: 0, totalTime: 0 };
+            callerData.count++;
+            callerData.totalTime += duration;
+            node.callers.set(parentHandle.name, callerData);
+            // 确保父节点存在
+            let parentNode = this.callGraph.get(parentHandle.name);
+            if (!parentNode) {
+                parentNode = {
+                    name: parentHandle.name,
+                    category: parentHandle.category,
+                    callCount: 0,
+                    totalTime: 0,
+                    callers: new Map(),
+                    callees: new Map()
+                };
+                this.callGraph.set(parentHandle.name, parentNode);
+            }
+            // 记录父函数调用了谁
+            const calleeData = parentNode.callees.get(name) || { count: 0, totalTime: 0 };
+            calleeData.count++;
+            calleeData.totalTime += duration;
+            parentNode.callees.set(name, calleeData);
+        }
+    }
+    aggregateSampleStats(frames) {
+        const aggregated = new Map();
+        for (const frame of frames) {
+            for (const stats of frame.sampleStats) {
+                let agg = aggregated.get(stats.name);
+                if (!agg) {
+                    agg = {
+                        ...stats,
+                        minTime: Number.MAX_VALUE
+                    };
+                    aggregated.set(stats.name, agg);
+                }
+                else {
+                    agg.inclusiveTime += stats.inclusiveTime;
+                    agg.exclusiveTime += stats.exclusiveTime;
+                    agg.callCount += stats.callCount;
+                    agg.minTime = Math.min(agg.minTime, stats.minTime);
+                    agg.maxTime = Math.max(agg.maxTime, stats.maxTime);
+                }
+            }
+        }
+        const totalTime = frames.reduce((sum, f) => sum + f.duration, 0);
+        for (const stats of aggregated.values()) {
+            stats.averageTime = stats.inclusiveTime / stats.callCount;
+            stats.percentOfFrame = (stats.inclusiveTime / totalTime) * 100;
+        }
+        return Array.from(aggregated.values());
+    }
+    aggregateCategoryStats(frames) {
+        const aggregated = new Map();
+        for (const frame of frames) {
+            for (const [category, stats] of frame.categoryStats) {
+                let agg = aggregated.get(category);
+                if (!agg) {
+                    agg = { totalTime: 0, frameCount: 0 };
+                    aggregated.set(category, agg);
+                }
+                agg.totalTime += stats.totalTime;
+                agg.frameCount++;
+            }
+        }
+        const totalTime = frames.reduce((sum, f) => sum + f.duration, 0);
+        const result = new Map();
+        for (const [category, agg] of aggregated) {
+            result.set(category, {
+                totalTime: agg.totalTime,
+                averageTime: agg.frameCount > 0 ? agg.totalTime / agg.frameCount : 0,
+                percentOfTotal: totalTime > 0 ? (agg.totalTime / totalTime) * 100 : 0
+            });
+        }
+        return result;
+    }
+    setupLongTaskObserver() {
+        if (typeof PerformanceObserver === 'undefined')
+            return;
+        try {
+            this.performanceObserver = new PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    if (entry.duration > this.config.longTaskThreshold) {
+                        this.longTasks.push({
+                            startTime: entry.startTime,
+                            duration: entry.duration,
+                            attribution: entry.attribution?.map((a) => a.name) || []
+                        });
+                        if (this.longTasks.length > 100) {
+                            this.longTasks.shift();
+                        }
+                    }
+                }
+            });
+            this.performanceObserver.observe({ entryTypes: ['longtask'] });
+        }
+        catch {
+            // Long Task API not supported
+        }
+    }
+    createEmptyReport() {
+        return {
+            startTime: 0,
+            endTime: 0,
+            totalFrames: 0,
+            averageFrameTime: 0,
+            minFrameTime: 0,
+            maxFrameTime: 0,
+            p95FrameTime: 0,
+            p99FrameTime: 0,
+            hotspots: [],
+            callGraph: new Map(),
+            categoryBreakdown: new Map(),
+            memoryTrend: [],
+            longTasks: []
+        };
+    }
+}
+ProfilerSDK.instance = null;
+//# sourceMappingURL=ProfilerSDK.js.map