@esengine/ecs-framework 2.3.0 → 2.3.1

package/bin/Utils/Profiler/ProfilerSDK.js

@@ -1,727 +0,0 @@
-/**
- * 性能分析器 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