traceperf 0.2.1 → 1.3.0

package/dist/esm/core/optimized-performance-monitor.js

@@ -10,6 +10,10 @@
  * 6. Module registration capability
  * 7. Enhanced visualization
  */
+import { coveredLength, formatTree, walkRecords, } from './records.js';
+import { StatsCollector, formatStatsTable } from './stats.js';
+import { createTraceRecorder } from './exporters.js';
+import { loadNodeBuiltin } from './env.js';
 // Define tracking mode constants directly to avoid circular dependency
 export const TrackingModes = {
     PERFORMANCE: 'performance',
@@ -19,12 +23,21 @@ export const TrackingModes = {
 };
 // Define default tracking mode separately to avoid circular dependency
 const DEFAULT_TRACKING_MODE = TrackingModes.BALANCED;
+// v8.getHeapStatistics() reports the same heap figure as
+// process.memoryUsage().heapUsed but ~20x faster (it skips measuring RSS).
+const v8Module = loadNodeBuiltin('v8');
+const readHeapUsed = v8Module && typeof v8Module.getHeapStatistics === 'function'
+    ? () => v8Module.getHeapStatistics().used_heap_size
+    : undefined;
 /**
  * Get current memory usage with environment detection
  * @returns Memory usage in bytes
  */
 export const getMemoryUsage = () => {
     var _a;
+    if (readHeapUsed) {
+        return readHeapUsed();
+    }
     // Safe check for Node.js process.memoryUsage()
     if (typeof process !== 'undefined' && process.memoryUsage) {
         const mem = process.memoryUsage();
@@ -32,8 +45,7 @@ export const getMemoryUsage = () => {
     }
     // Browser memory API if available
     else if (typeof performance !== 'undefined' && 'memory' in performance) {
-        // @ts-expect-error This is a browser-specific check
-        return ((_a = window.performance.memory) === null || _a === void 0 ? void 0 : _a.usedJSHeapSize) || 0;
+        return ((_a = performance.memory) === null || _a === void 0 ? void 0 : _a.usedJSHeapSize) || 0;
     }
     // Fallback when no memory API available
     return 0;
@@ -42,19 +54,16 @@ export const getMemoryUsage = () => {
  * Get high-resolution timestamp with environment detection
  * @returns Timestamp in nanoseconds
  */
-export const getTimestamp = () => {
-    // Use performance.now() in browsers (convert to nanoseconds)
-    if (typeof performance !== 'undefined' && performance.now) {
-        return performance.now() * 1000000;
-    }
-    // Use process.hrtime() in Node.js
-    else if (typeof process !== 'undefined' && process.hrtime) {
-        const hrTime = process.hrtime();
-        return hrTime[0] * 1000000000 + hrTime[1];
-    }
-    // Fallback to Date.now() (converted to nanoseconds)
-    return Date.now() * 1000000;
-};
+export const getTimestamp = 
+// Clock chosen once at load time (the hot path should not re-detect it)
+typeof performance !== 'undefined' && typeof performance.now === 'function'
+    ? () => performance.now() * 1000000
+    : typeof process !== 'undefined' && typeof process.hrtime === 'function'
+        ? () => {
+            const hrTime = process.hrtime();
+            return hrTime[0] * 1000000000 + hrTime[1];
+        }
+        : () => Date.now() * 1000000;
 /**
  * Calculate time difference between two timestamps
  * @param startTime Starting timestamp in nanoseconds
@@ -63,6 +72,91 @@ export const getTimestamp = () => {
 export const getDuration = (startTime) => {
     return getTimestamp() - startTime;
 };
+// Offset from the monotonic clock (ms) to Unix epoch ms, fixed at load time
+const EPOCH_OFFSET_MS = Date.now() - getTimestamp() / 1000000;
+const MAX_ARG_LENGTH = 50;
+/**
+ * Render one captured argument as a short, safe string.
+ * Never throws and never walks large structures in full.
+ */
+export const formatArg = (arg) => {
+    var _a, _b;
+    let text;
+    try {
+        if (typeof arg === 'string') {
+            text = JSON.stringify(arg.length > MAX_ARG_LENGTH ? arg.slice(0, MAX_ARG_LENGTH) : arg);
+        }
+        else if (typeof arg === 'function') {
+            text = `[Function ${arg.name || 'anonymous'}]`;
+        }
+        else if (Array.isArray(arg)) {
+            text = `Array(${arg.length})`;
+        }
+        else if (arg !== null && typeof arg === 'object') {
+            const keys = Object.keys(arg);
+            if (keys.length <= 5) {
+                text = JSON.stringify(arg);
+            }
+            else {
+                const name = ((_a = arg.constructor) === null || _a === void 0 ? void 0 : _a.name) || 'Object';
+                text = `${name}{${keys.length} keys}`;
+            }
+        }
+        else {
+            text = String(arg);
+        }
+    }
+    catch (_c) {
+        // circular structures, null prototypes, throwing getters/toJSON, ...
+        const name = (_b = arg === null || arg === void 0 ? void 0 : arg.constructor) === null || _b === void 0 ? void 0 : _b.name;
+        text = typeof name === 'string' && name ? `[${name}]` : '[object]';
+    }
+    return text.length > MAX_ARG_LENGTH ? `${text.slice(0, MAX_ARG_LENGTH - 1)}…` : text;
+};
+const loadAsyncLocalStorage = () => {
+    var _a, _b;
+    return (_b = (_a = loadNodeBuiltin('async_hooks')) === null || _a === void 0 ? void 0 : _a.AsyncLocalStorage) !== null && _b !== void 0 ? _b : 
+    // Edge runtimes (e.g. Next.js Edge) expose it as a global
+    (typeof globalThis !== 'undefined' ? globalThis.AsyncLocalStorage : undefined);
+};
+const createExecutionContext = (provided) => {
+    const AsyncLocalStorage = provided !== null && provided !== void 0 ? provided : loadAsyncLocalStorage();
+    if (AsyncLocalStorage) {
+        const storage = new AsyncLocalStorage();
+        return {
+            current: () => { var _a; return (_a = storage.getStore()) !== null && _a !== void 0 ? _a : null; },
+            run: (executionId, fn) => storage.run(executionId, fn),
+            // AsyncLocalStorage.run forwards extra arguments to the callback
+            apply: (executionId, fn, thisArg, args) => storage.run(executionId, Reflect.apply, fn, thisArg, args)
+        };
+    }
+    let current = null;
+    const run = (executionId, fn) => {
+        const previous = current;
+        current = executionId;
+        try {
+            return fn();
+        }
+        finally {
+            current = previous;
+        }
+    };
+    return {
+        current: () => current,
+        run,
+        apply: (executionId, fn, thisArg, args) => run(executionId, () => fn.apply(thisArg, args))
+    };
+};
+const NOOP_SPAN = {
+    id: '',
+    setLabel: () => undefined,
+    run: (fn) => fn(),
+    end: () => undefined
+};
+const clampRate = (rate) => Math.max(0, Math.min(1, rate));
+const isNativePromise = (value) => value !== null && typeof value === 'object' &&
+    (value instanceof Promise ||
+        (typeof value.then === 'function' && Object.prototype.toString.call(value) === '[object Promise]'));
 /**
  * Optimized tracker for individual function executions
  */
@@ -72,25 +166,85 @@ export class OptimizedExecutionTracker {
      * @param options Tracker configuration options
      */
     constructor(options = {}) {
-        var _a, _b, _c, _d, _e;
-        this.executionTree = {};
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        this.executionTree = new Map();
         this.currentExecutionId = 0;
         this.activeExecutions = new Map();
-        // Formatters for flow chart generation
-        this._formatters = {
-            indent: '  ',
-            childPrefix: '├─ ',
-            lastChildPrefix: '└─ ',
-            linePrefix: '│  ',
-            emptyPrefix: '   ',
-            errorMarker: '✖ ',
-            memoryLabel: '📊 '
-        };
+        this.plugins = [];
+        this.wrappers = [];
+        this.failedPlugins = new Set();
         this.showMemoryUsage = (_a = options.showMemoryUsage) !== null && _a !== void 0 ? _a : true;
         this.enableNestedTracking = (_b = options.enableNestedTracking) !== null && _b !== void 0 ? _b : true;
         this.silent = (_c = options.silent) !== null && _c !== void 0 ? _c : false;
         this.trackingMode = (_d = options.trackingMode) !== null && _d !== void 0 ? _d : TrackingModes.BALANCED;
-        this.defaultThreshold = (_e = options.threshold) !== null && _e !== void 0 ? _e : 100;
+        this.defaultThreshold = (_e = options.threshold) !== null && _e !== void 0 ? _e : 0;
+        this.defaultSampleRate = clampRate((_f = options.sampleRate) !== null && _f !== void 0 ? _f : 1);
+        this.context = createExecutionContext(options.asyncLocalStorage);
+        this.enabled = (_g = options.enabled) !== null && _g !== void 0 ? _g : true;
+        this.blockingThreshold = (_h = options.blockingThreshold) !== null && _h !== void 0 ? _h : 50;
+        this.reporter = (_j = options.reporter) !== null && _j !== void 0 ? _j : null;
+        this.stats = options.stats === false ? null :
+            new StatsCollector(typeof options.stats === 'object' ? options.stats : {});
+        (options.plugins || []).forEach(plugin => this.use(plugin));
+    }
+    /**
+     * Register a plugin. Returns a function that removes it again.
+     */
+    use(plugin) {
+        this.plugins = [...this.plugins, plugin];
+        this.wrappers = this.plugins.filter(p => typeof p.wrap === 'function');
+        return () => {
+            this.plugins = this.plugins.filter(p => p !== plugin);
+            this.wrappers = this.plugins.filter(p => typeof p.wrap === 'function');
+        };
+    }
+    /**
+     * Run `run` inside every plugin's wrap() (first registered = outermost).
+     * A wrap() that throws before calling run is reported once and skipped.
+     */
+    _wrap(execution, run) {
+        let next = run;
+        for (let i = this.wrappers.length - 1; i >= 0; i--) {
+            const plugin = this.wrappers[i];
+            const inner = next;
+            next = () => {
+                let ran = false;
+                const once = () => {
+                    ran = true;
+                    return inner();
+                };
+                try {
+                    return plugin.wrap(execution, once);
+                }
+                catch (error) {
+                    if (ran)
+                        throw error; // the tracked code itself threw
+                    this._pluginFailed(plugin, 'wrap', error);
+                    return inner();
+                }
+            };
+        }
+        return next();
+    }
+    _pluginFailed(plugin, hook, error) {
+        if (!this.failedPlugins.has(plugin)) {
+            this.failedPlugins.add(plugin);
+            console.warn(`traceperf: plugin ${plugin.name || '(unnamed)'} threw in ${hook}:`, error);
+        }
+    }
+    _callPlugins(hook, payload) {
+        for (const plugin of this.plugins) {
+            const fn = plugin[hook];
+            if (!fn)
+                continue;
+            try {
+                fn.call(plugin, payload);
+            }
+            catch (error) {
+                // Never let a plugin break the tracked code; warn once per plugin
+                this._pluginFailed(plugin, hook, error);
+            }
+        }
     }
     /**
      * Start timing a function execution
@@ -99,9 +253,13 @@ export class OptimizedExecutionTracker {
      * @param options Additional options
      * @returns Execution ID
      */
-    startTimer(label, parentExecutionId = null, options = {}) {
+    startTimer(label, parentExecutionId = null, options = {}, args = options.args) {
+        var _a, _b, _c, _d;
+        // Per-execution settings, falling back to the tracker's current config
+        const trackingMode = (_a = options.trackingMode) !== null && _a !== void 0 ? _a : this.trackingMode;
+        const trackMemory = (_b = options.trackMemory) !== null && _b !== void 0 ? _b : this.showMemoryUsage;
         // Skip detailed tracking in performance mode
-        const collectMemory = this.trackingMode !== TrackingModes.PERFORMANCE && this.showMemoryUsage;
+        const collectMemory = trackingMode !== TrackingModes.PERFORMANCE && trackMemory;
         const startTime = getTimestamp();
         const executionId = (++this.currentExecutionId).toString();
         const execution = {
@@ -112,9 +270,12 @@ export class OptimizedExecutionTracker {
             duration: 0,
             parentId: parentExecutionId,
             children: [],
-            args: options.captureArgs && options.args ?
-                Array.from(options.args).map(arg => String(arg).substring(0, 50)) : [],
-            complete: false
+            args: options.captureArgs && args ?
+                Array.from(args).map(formatArg) : undefined,
+            complete: false,
+            silent: (_c = options.silent) !== null && _c !== void 0 ? _c : this.silent,
+            trackingMode,
+            threshold: (_d = options.threshold) !== null && _d !== void 0 ? _d : this.defaultThreshold
         };
         // Collect memory usage if enabled
         if (collectMemory) {
@@ -131,6 +292,14 @@ export class OptimizedExecutionTracker {
         }
         // Store in active executions map
         this.activeExecutions.set(executionId, execution);
+        if (this.plugins.length > 0) {
+            this._callPlugins('onStart', {
+                id: executionId,
+                label: execution.label,
+                parentId: parentExecutionId,
+                startEpochMs: EPOCH_OFFSET_MS + startTime / 1000000
+            });
+        }
         return executionId;
     }
     /**
@@ -145,69 +314,185 @@ export class OptimizedExecutionTracker {
             return null;
         }
         const execution = this.activeExecutions.get(executionId);
+        this.activeExecutions.delete(executionId);
         execution.endTime = getTimestamp();
         execution.duration = execution.endTime - execution.startTime;
         execution.result = result;
         execution.error = error;
         execution.complete = true;
-        // Only collect memory in non-performance modes
-        if (this.trackingMode !== TrackingModes.PERFORMANCE && this.showMemoryUsage) {
+        // Only collect memory if it was collected at start
+        if (execution.memoryAtStart !== undefined) {
             execution.memoryAtEnd = getMemoryUsage();
             execution.memoryDelta = execution.memoryAtEnd - (execution.memoryAtStart || 0);
         }
-        // Store in the execution tree
-        this.executionTree[executionId] = { ...execution };
-        // Generate flow chart if not silent
-        if (!this.silent && this.trackingMode !== TrackingModes.PERFORMANCE) {
-            const flowChart = this._generateExecutionFlowChart(execution);
-            console.log(flowChart);
+        // A child whose parent is still running is reported as part of the
+        // parent's tree once the parent finishes.
+        const parentRunning = execution.parentId !== null && this.activeExecutions.has(execution.parentId);
+        if (parentRunning) {
+            this.executionTree.set(executionId, execution);
+            return execution;
+        }
+        // Root (or a child that outlived its parent): build the record tree once
+        // and hand it to stats, the console reporter and plugins.
+        const record = this._toRecord(execution);
+        // Release the finished tree so memory use does not grow with call count
+        if (execution.children.length > 0) {
+            this._release(execution);
+        }
+        if (this.stats) {
+            this.stats.addTree(record);
+        }
+        if (!record.silent &&
+            record.trackingMode !== TrackingModes.PERFORMANCE &&
+            record.duration >= record.threshold) {
+            this._report(record);
+        }
+        if (this.plugins.length > 0) {
+            this._callPlugins('onComplete', record);
         }
         return execution;
     }
     /**
-     * Generate a visualization of the execution flow
-     * @param execution The execution to visualize
-     * @param depth Current depth in the tree
-     * @param isLastChild Whether this is the last child
-     * @param ancestors Array tracking if parents were last children
-     * @returns Formatted execution flow chart
-     */
-    _generateExecutionFlowChart(execution, depth = 0, isLastChild = true, ancestors = []) {
-        // Skip in performance mode
-        if (this.trackingMode === TrackingModes.PERFORMANCE) {
-            return '';
-        }
-        // Build the flow chart
-        let flowChart = '';
-        // Format the execution line based on tracking mode
-        const durationStr = (execution.duration / 1000000).toFixed(3);
-        const formatters = this._formatters;
-        let line = `${formatters.indent.repeat(depth)}${isLastChild ? formatters.lastChildPrefix : formatters.childPrefix}${execution.label}: ${durationStr} ms`;
-        // Add memory usage if enabled and in detailed modes
-        if (this.showMemoryUsage &&
-            execution.memoryDelta !== undefined &&
-            this.trackingMode !== TrackingModes.PERFORMANCE) {
-            const memoryStr = (execution.memoryDelta / 1024).toFixed(2);
-            const sign = execution.memoryDelta >= 0 ? '+' : '';
-            line += ` ${formatters.memoryLabel}${sign}${memoryStr} KB`;
-        }
-        // Add error indicator
-        if (execution.error && (this.trackingMode === TrackingModes.DETAILED || this.trackingMode === TrackingModes.DEBUG)) {
-            line += ` ${formatters.errorMarker}${execution.error.message}`;
-        }
-        flowChart += line + '\n';
-        // Process children (skip in performance mode)
-        if (execution.children && execution.children.length > 0 && this.trackingMode !== TrackingModes.PERFORMANCE) {
-            const childExecutions = execution.children
-                .map(childId => this.executionTree[childId] || this.activeExecutions.get(childId))
-                .filter(Boolean);
-            for (let i = 0; i < childExecutions.length; i++) {
-                const isLast = i === childExecutions.length - 1;
-                const childFlowChart = this._generateExecutionFlowChart(childExecutions[i], depth + 1, isLast, [...ancestors, !isLastChild]);
-                flowChart += childFlowChart;
+     * Drop a finished execution and its finished descendants
+     */
+    _release(execution) {
+        for (const childId of execution.children) {
+            const child = this.executionTree.get(childId);
+            if (child) {
+                this.executionTree.delete(childId);
+                this._release(child);
+            }
+        }
+    }
+    /**
+     * Mark the end of the synchronous part of an execution that returned a promise
+     */
+    markSyncEnd(executionId) {
+        const execution = this.activeExecutions.get(executionId);
+        if (execution) {
+            execution.syncEndTime = getTimestamp();
+        }
+    }
+    /**
+     * Convert a finished execution (and its finished children) to a record tree
+     */
+    _toRecord(execution) {
+        var _a, _b, _c;
+        const startTime = execution.startTime / 1000000;
+        const endTime = execution.endTime / 1000000;
+        const duration = execution.duration / 1000000;
+        const children = [];
+        let covered = 0;
+        if (execution.children.length > 0) {
+            for (const childId of execution.children) {
+                const child = this.executionTree.get(childId);
+                if (child) {
+                    children.push(this._toRecord(child));
+                }
             }
+            covered = coveredLength(children.map(c => [Math.max(c.startTime, startTime), Math.min(c.endTime, endTime)]));
+        }
+        const isAsync = execution.syncEndTime !== undefined;
+        const record = {
+            id: execution.id,
+            label: execution.label,
+            parentId: execution.parentId,
+            startTime,
+            endTime,
+            startEpochMs: EPOCH_OFFSET_MS + startTime,
+            duration,
+            selfDuration: Math.max(0, duration - covered),
+            syncDuration: isAsync ? (execution.syncEndTime - execution.startTime) / 1000000 : duration,
+            async: isAsync,
+            children,
+            threshold: (_a = execution.threshold) !== null && _a !== void 0 ? _a : 0,
+            trackingMode: (_b = execution.trackingMode) !== null && _b !== void 0 ? _b : this.trackingMode,
+            silent: (_c = execution.silent) !== null && _c !== void 0 ? _c : this.silent,
+        };
+        if (execution.memoryAtStart !== undefined && execution.memoryDelta !== undefined) {
+            record.memoryDelta = execution.memoryDelta;
+        }
+        if (execution.error !== null && execution.error !== undefined) {
+            record.error = execution.error;
+        }
+        if (execution.args && execution.args.length > 0) {
+            record.args = execution.args;
         }
-        return flowChart;
+        return record;
+    }
+    /**
+     * Print a finished tree (or hand it to the custom reporter)
+     */
+    _report(record) {
+        if (this.reporter) {
+            this.reporter(record);
+            return;
+        }
+        const detailed = record.trackingMode === TrackingModes.DETAILED || record.trackingMode === TrackingModes.DEBUG;
+        console.log(formatTree(record, {
+            detailed,
+            showErrors: detailed,
+            blockingThreshold: this.blockingThreshold
+        }));
+    }
+    /**
+     * Run one call of `fn` with tracking (shared by createTrackable and track)
+     */
+    _invoke(fn, thisArg, args, options, label) {
+        // Disabled: call straight through
+        if (!this.enabled) {
+            return fn.apply(thisArg, args);
+        }
+        // Apply sampling - randomly decide whether to track this call
+        const sampleRate = options.sampleRate !== undefined ?
+            clampRate(options.sampleRate) : this.defaultSampleRate;
+        const shouldSample = Math.random() < sampleRate;
+        // If not sampling this call, just execute the function directly
+        if (!shouldSample) {
+            return fn.apply(thisArg, args);
+        }
+        const nested = this.enableNestedTracking && options.enableNestedTracking !== false;
+        const explicitParentId = options.parentExecutionId || null;
+        const parentExecutionId = explicitParentId !== null && explicitParentId !== void 0 ? explicitParentId : (nested ? this.context.current() : null);
+        // Start tracking the execution
+        // The options object already has the TimerOptions fields; pass it as is
+        const executionId = this.startTimer(label, parentExecutionId, options, args);
+        let result;
+        try {
+            // Execute the function with the caller's `this`, as the current
+            // execution so nested tracked calls attach to it
+            if (this.wrappers.length > 0) {
+                result = this._wrap({ id: executionId, label, parentId: parentExecutionId }, () => (nested ?
+                    this.context.apply(executionId, fn, thisArg, args) :
+                    fn.apply(thisArg, args)));
+            }
+            else {
+                result = nested ?
+                    this.context.apply(executionId, fn, thisArg, args) :
+                    fn.apply(thisArg, args);
+            }
+        }
+        catch (error) {
+            // Handle synchronous errors
+            this.endTimer(executionId, undefined, error);
+            throw error; // Re-throw to preserve error behavior
+        }
+        // Native promises (incl. async functions): time until settled.
+        // Other thenables are returned untouched - calling their then() could
+        // trigger side effects (e.g. query builders) or change their type.
+        if (isNativePromise(result)) {
+            this.markSyncEnd(executionId);
+            return result.then((resolvedValue) => {
+                this.endTimer(executionId, resolvedValue);
+                return resolvedValue;
+            }, (error) => {
+                this.endTimer(executionId, undefined, error);
+                throw error; // Re-throw to preserve error behavior
+            });
+        }
+        // Handle synchronous functions
+        this.endTimer(executionId, result);
+        return result;
     }
     /**
      * Create a trackable version of a function
@@ -216,65 +501,80 @@ export class OptimizedExecutionTracker {
      * @returns Tracked version of the function
      */
     createTrackable(fn, options = {}) {
+        var _a;
         if (typeof fn !== 'function') {
             throw new Error('First argument must be a function');
         }
         const label = options.label || fn.name || 'anonymous';
-        const parentExecutionId = options.parentExecutionId || null;
-        const silent = options.hasOwnProperty('silent') ? options.silent : this.silent;
+        const silent = (_a = options.silent) !== null && _a !== void 0 ? _a : this.silent;
         const trackingMode = options.trackingMode || this.trackingMode;
-        const sampleRate = options.hasOwnProperty('sampleRate') ?
-            Math.max(0, Math.min(1, options.sampleRate)) : 1.0;
         // Performance optimization - if in performance mode and silent, return original function
         if (trackingMode === TrackingModes.PERFORMANCE &&
-            (options.silent || this.silent) &&
+            silent &&
             !this.enableNestedTracking) {
             return fn;
         }
-        // Create the tracked function using arrow function to preserve 'this'
-        const trackedFn = (...args) => {
-            // Apply sampling - randomly decide whether to track this call
-            const shouldSample = Math.random() < sampleRate;
-            // If not sampling this call, just execute the function directly
-            if (!shouldSample) {
-                return fn.apply(this, args);
-            }
-            // Start tracking the execution
-            const executionId = this.startTimer(label, parentExecutionId, {
-                trackMemory: options.trackMemory !== undefined ? options.trackMemory : this.showMemoryUsage,
-                captureArgs: options.captureArgs,
-                args: args
-            });
-            try {
-                // Execute the function with correct this context
-                const result = fn.apply(this, args);
-                // Handle promises
-                if (result && typeof result.then === 'function') {
-                    return result
-                        .then((resolvedValue) => {
-                        this.endTimer(executionId, resolvedValue);
-                        return resolvedValue;
-                    })
-                        .catch((error) => {
-                        this.endTimer(executionId, undefined, error);
-                        throw error; // Re-throw to preserve error behavior
-                    });
-                }
-                // Handle synchronous functions
-                this.endTimer(executionId, result);
-                return result;
-            }
-            catch (error) {
-                // Handle synchronous errors
-                this.endTimer(executionId, undefined, error);
-                throw error; // Re-throw to preserve error behavior
-            }
+        const invoke = (thisArg, args) => this._invoke(fn, thisArg, args, options, label);
+        // A regular function (not an arrow) so callers keep their own `this`
+        const trackedFn = function (...args) {
+            return invoke(this, args);
         };
         // Preserve function properties
         Object.defineProperty(trackedFn, 'name', { value: fn.name, configurable: true });
         Object.defineProperty(trackedFn, 'length', { value: fn.length });
         return trackedFn;
     }
+    /**
+     * Start a manually-ended execution (a "span"). Use `run()` to execute code
+     * as part of it, so tracked calls inside attach as children, and `end()`
+     * when the work is finished.
+     */
+    startSpan(label, options = {}) {
+        if (!this.enabled) {
+            return NOOP_SPAN;
+        }
+        const sampleRate = options.sampleRate !== undefined ? clampRate(options.sampleRate) : this.defaultSampleRate;
+        if (!(Math.random() < sampleRate)) {
+            return NOOP_SPAN;
+        }
+        const nested = this.enableNestedTracking && options.enableNestedTracking !== false;
+        const explicitParentId = options.parentExecutionId || null;
+        const parentExecutionId = explicitParentId !== null && explicitParentId !== void 0 ? explicitParentId : (nested ? this.context.current() : null);
+        const executionId = this.startTimer(label || 'anonymous', parentExecutionId, {
+            trackMemory: options.trackMemory,
+            silent: options.silent,
+            trackingMode: options.trackingMode,
+            threshold: options.threshold
+        });
+        let ended = false;
+        return {
+            id: executionId,
+            setLabel: (newLabel) => {
+                const execution = this.activeExecutions.get(executionId);
+                if (execution && newLabel) {
+                    execution.label = newLabel;
+                }
+            },
+            run: (fn) => {
+                const runInContext = () => (nested ? this.context.run(executionId, fn) : fn());
+                const result = this.wrappers.length > 0 ?
+                    this._wrap({ id: executionId, label: label || 'anonymous', parentId: parentExecutionId }, runInContext) :
+                    runInContext();
+                // The span's synchronous part ends when its first run() returns
+                const execution = this.activeExecutions.get(executionId);
+                if (execution && execution.syncEndTime === undefined) {
+                    execution.syncEndTime = getTimestamp();
+                }
+                return result;
+            },
+            end: (error) => {
+                if (ended)
+                    return;
+                ended = true;
+                this.endTimer(executionId, undefined, (error !== null && error !== void 0 ? error : null));
+            }
+        };
+    }
     /**
      * Track a module's methods
      * @param module Module to track
@@ -282,6 +582,7 @@ export class OptimizedExecutionTracker {
      * @returns Tracked module
      */
     trackModule(module, options = {}) {
+        var _a;
         if (!module || typeof module !== 'object') {
             throw new Error('Module must be an object');
         }
@@ -289,7 +590,7 @@ export class OptimizedExecutionTracker {
         const trackingMode = options.trackingMode || this.trackingMode;
         // Performance optimization - if in performance mode and silent, return original module
         if (trackingMode === TrackingModes.PERFORMANCE &&
-            (options.silent || this.silent) &&
+            ((_a = options.silent) !== null && _a !== void 0 ? _a : this.silent) &&
             !this.enableNestedTracking) {
             return module;
         }
@@ -322,17 +623,29 @@ export class OptimizedExecutionTracker {
      * @returns Function result
      */
     track(fn, options = {}) {
-        // Create a trackable version and call it immediately
-        const trackableFn = this.createTrackable(fn, options);
-        return trackableFn.apply(options.thisContext || this, options.args || []);
+        var _a;
+        if (typeof fn !== 'function') {
+            throw new Error('First argument must be a function');
+        }
+        // Same fast path as createTrackable, without building a wrapper per call
+        if ((options.trackingMode || this.trackingMode) === TrackingModes.PERFORMANCE &&
+            ((_a = options.silent) !== null && _a !== void 0 ? _a : this.silent) &&
+            !this.enableNestedTracking) {
+            return fn.apply(options.thisContext, options.args || []);
+        }
+        const label = options.label || fn.name || 'anonymous';
+        return this._invoke(fn, options.thisContext, (options.args || []), options, label);
     }
     /**
      * Reset the tracker state
      */
     reset() {
-        this.executionTree = {};
+        this.executionTree = new Map();
         this.currentExecutionId = 0;
         this.activeExecutions = new Map();
+        if (this.stats) {
+            this.stats.reset();
+        }
     }
 }
 /**
@@ -344,22 +657,34 @@ export class OptimizedPerformanceMonitor {
      * @param options Configuration options
      */
     constructor(options = {}) {
+        var _a, _b, _c;
         this.config = {
             trackingMode: options.trackingMode || DEFAULT_TRACKING_MODE,
             silent: options.silent || false,
             trackMemory: options.trackMemory !== undefined ? options.trackMemory : true,
             enableNestedTracking: options.enableNestedTracking !== undefined ? options.enableNestedTracking : true,
-            threshold: options.threshold || 100,
-            sampleRate: options.sampleRate !== undefined ?
-                Math.max(0, Math.min(1, options.sampleRate)) : 1.0 // Clamp between 0 and 1
+            threshold: (_a = options.threshold) !== null && _a !== void 0 ? _a : 0,
+            sampleRate: options.sampleRate !== undefined ? clampRate(options.sampleRate) : 1.0,
+            enabled: (_b = options.enabled) !== null && _b !== void 0 ? _b : true,
+            blockingThreshold: (_c = options.blockingThreshold) !== null && _c !== void 0 ? _c : 50
         };
         this.executionTracker = new OptimizedExecutionTracker({
             trackingMode: this.config.trackingMode,
             silent: this.config.silent,
             showMemoryUsage: this.config.trackMemory,
             enableNestedTracking: this.config.enableNestedTracking,
-            threshold: this.config.threshold
+            threshold: this.config.threshold,
+            sampleRate: this.config.sampleRate,
+            enabled: this.config.enabled,
+            blockingThreshold: this.config.blockingThreshold,
+            stats: options.stats,
+            reporter: options.reporter,
+            plugins: options.plugins,
+            asyncLocalStorage: options.asyncLocalStorage
         });
+        if (options.onComplete) {
+            this.onComplete(options.onComplete);
+        }
     }
     /**
      * Track a function execution
@@ -371,20 +696,9 @@ export class OptimizedPerformanceMonitor {
         if (typeof fn !== 'function') {
             throw new Error('First argument must be a function');
         }
-        // Merge global config with function-specific options
-        const trackingOptions = {
-            label: options.label || fn.name || 'anonymous',
-            trackingMode: options.trackingMode || this.config.trackingMode,
-            silent: options.hasOwnProperty('silent') ? options.silent : this.config.silent,
-            trackMemory: options.hasOwnProperty('trackMemory') ? options.trackMemory : this.config.trackMemory,
-            sampleRate: options.hasOwnProperty('sampleRate') ? options.sampleRate : this.config.sampleRate,
-            captureArgs: options.hasOwnProperty('captureArgs') ? options.captureArgs : false,
-            parentExecutionId: options.parentExecutionId || null,
-            thisContext: options.thisContext,
-            args: options.args
-        };
-        // Use the tracker to directly track the function
-        return this.executionTracker.track(fn, trackingOptions);
+        // Only per-call options are passed down; anything left out falls back to
+        // this instance's *current* configuration when the call runs.
+        return this.executionTracker.track(fn, options);
     }
     /**
      * Create a trackable version of a function
@@ -396,17 +710,7 @@ export class OptimizedPerformanceMonitor {
         if (typeof fn !== 'function') {
             throw new Error('First argument must be a function');
         }
-        // Merge global config with function-specific options
-        const trackingOptions = {
-            label: options.label || fn.name || 'anonymous',
-            trackingMode: options.trackingMode || this.config.trackingMode,
-            silent: options.hasOwnProperty('silent') ? options.silent : this.config.silent,
-            trackMemory: options.hasOwnProperty('trackMemory') ? options.trackMemory : this.config.trackMemory,
-            sampleRate: options.hasOwnProperty('sampleRate') ? options.sampleRate : this.config.sampleRate,
-            captureArgs: options.hasOwnProperty('captureArgs') ? options.captureArgs : false,
-            parentExecutionId: options.parentExecutionId || null
-        };
-        return this.executionTracker.createTrackable(fn, trackingOptions);
+        return this.executionTracker.createTrackable(fn, options);
     }
     /**
      * Register a module for tracking
@@ -418,16 +722,201 @@ export class OptimizedPerformanceMonitor {
         if (!module || typeof module !== 'object') {
             throw new Error('Module must be an object');
         }
-        // Merge global config with module-specific options
-        const trackingOptions = {
-            prefix: options.prefix || '',
-            trackingMode: options.trackingMode || this.config.trackingMode,
-            silent: options.hasOwnProperty('silent') ? options.silent : this.config.silent,
-            trackMemory: options.hasOwnProperty('trackMemory') ? options.trackMemory : this.config.trackMemory,
-            sampleRate: options.hasOwnProperty('sampleRate') ? options.sampleRate : this.config.sampleRate,
-            captureArgs: options.hasOwnProperty('captureArgs') ? options.captureArgs : false
+        return this.executionTracker.trackModule(module, options);
+    }
+    /**
+     * Track every method of an object or class instance, including methods
+     * inherited from its prototype, without copying it. Returns a proxy:
+     * state changes go to the original object, and methods run with the
+     * original object as `this` (so private #fields keep working).
+     */
+    trackObject(target, options = {}) {
+        var _a;
+        if (!target || (typeof target !== 'object' && typeof target !== 'function')) {
+            throw new Error('trackObject expects an object');
+        }
+        const ctorName = target.constructor && target.constructor !== Object
+            ? target.constructor.name : '';
+        const prefix = (_a = options.prefix) !== null && _a !== void 0 ? _a : (ctorName ? `${ctorName}.` : '');
+        const trackOptions = { ...options };
+        delete trackOptions.prefix;
+        const cache = new Map();
+        const wrap = (original, key, proxy) => {
+            var _a;
+            const tracked = this.createTrackable(original, {
+                ...trackOptions,
+                label: (_a = trackOptions.label) !== null && _a !== void 0 ? _a : `${prefix}${key}`
+            });
+            return function (...args) {
+                return tracked.apply(this === proxy ? target : this, args);
+            };
         };
-        return this.executionTracker.trackModule(module, trackingOptions);
+        const proxy = new Proxy(target, {
+            get: (obj, key, receiver) => {
+                const value = Reflect.get(obj, key, receiver);
+                if (typeof value !== 'function' || typeof key === 'symbol' || key === 'constructor' ||
+                    Object.prototype[key] === value) {
+                    return value;
+                }
+                const hit = cache.get(key);
+                if (hit && hit.original === value) {
+                    return hit.tracked;
+                }
+                const tracked = wrap(value, key, proxy);
+                cache.set(key, { original: value, tracked });
+                return tracked;
+            }
+        });
+        return proxy;
+    }
+    /**
+     * Method decorator. Works with TypeScript 5 / TC39 standard decorators and
+     * with legacy `experimentalDecorators`. The label defaults to
+     * "ClassName.method".
+     *
+     *   class UserService {
+     *     @tp.traced()
+     *     async getUser(id: string) { ... }
+     *   }
+     */
+    traced(options = {}) {
+        const trackables = new Map();
+        const trackedFor = (fn, label) => {
+            let tracked = trackables.get(label);
+            if (!tracked) {
+                tracked = this.createTrackable(fn, { ...options, label });
+                trackables.set(label, tracked);
+            }
+            return tracked;
+        };
+        const ownerName = (receiver) => { var _a; return typeof receiver === 'function' ? receiver.name : ((_a = receiver === null || receiver === void 0 ? void 0 : receiver.constructor) === null || _a === void 0 ? void 0 : _a.name) || 'anonymous'; };
+        const wrapMethod = (fn, methodName) => {
+            const wrapped = function (...args) {
+                var _a;
+                const label = (_a = options.label) !== null && _a !== void 0 ? _a : `${ownerName(this)}.${methodName}`;
+                return trackedFor(fn, label).apply(this, args);
+            };
+            Object.defineProperty(wrapped, 'name', { value: fn.name, configurable: true });
+            Object.defineProperty(wrapped, 'length', { value: fn.length, configurable: true });
+            return wrapped;
+        };
+        return (target, context, descriptor) => {
+            // Standard decorators: (method, context)
+            if (typeof target === 'function' && context && typeof context === 'object' && 'kind' in context) {
+                if (context.kind !== 'method') {
+                    throw new TypeError('@traced can only decorate methods');
+                }
+                return wrapMethod(target, String(context.name));
+            }
+            // Legacy decorators: (prototype or constructor, key, descriptor)
+            if (descriptor && typeof descriptor.value === 'function') {
+                descriptor.value = wrapMethod(descriptor.value, String(context));
+                return descriptor;
+            }
+            throw new TypeError('@traced can only decorate methods');
+        };
+    }
+    /**
+     * Start a manually-ended execution (a span), e.g. for a request:
+     *
+     *   const span = tp.start('GET /users');
+     *   span.run(() => next());      // tracked calls inside become children
+     *   res.on('finish', () => span.end());
+     */
+    start(label, options = {}) {
+        return this.executionTracker.startSpan(label, options);
+    }
+    /**
+     * Register a plugin (exporter, custom sink). Returns an unsubscribe function.
+     */
+    use(plugin) {
+        return this.executionTracker.use(plugin);
+    }
+    /**
+     * Call `listener` with every finished top-level execution tree (even when
+     * silent or below threshold). Returns an unsubscribe function.
+     */
+    onComplete(listener) {
+        return this.use({ name: 'onComplete', onComplete: listener });
+    }
+    /**
+     * Call `listener` for every finished call (nested ones included) that
+     * took at least `threshold` ms. Pass a number, or per-label thresholds
+     * with an optional '*' default:
+     *
+     *   tp.onSlow(200, (call, root) => logger.warn(`${call.label} took ${call.duration}ms in ${root.label}`));
+     *   tp.onSlow({ 'db.query': 50, 'GET /search': 500, '*': 1000 }, alert);
+     *
+     * Works in every tracking mode and when silent. Returns an unsubscribe function.
+     */
+    onSlow(threshold, listener) {
+        const limitFor = typeof threshold === 'number'
+            ? () => threshold
+            : (label) => (label in threshold ? threshold[label] : threshold['*']);
+        return this.use({
+            name: 'onSlow',
+            onComplete: root => {
+                walkRecords(root, record => {
+                    const limit = limitFor(record.label);
+                    if (limit !== undefined && record.duration >= limit)
+                        listener(record, root);
+                });
+            }
+        });
+    }
+    getStats(label) {
+        const stats = this.executionTracker.stats;
+        if (label !== undefined) {
+            return stats ? stats.get(label) : undefined;
+        }
+        return stats ? stats.all() : {};
+    }
+    /** Clear collected statistics */
+    resetStats() {
+        if (this.executionTracker.stats) {
+            this.executionTracker.stats.reset();
+        }
+        return this;
+    }
+    /** Statistics as a text table, slowest total first */
+    formatStats() {
+        return formatStatsTable(this.getStats());
+    }
+    /** Print the statistics table to the console */
+    printStats() {
+        console.log(this.formatStats());
+        return this;
+    }
+    /**
+     * Start recording finished calls for a Chrome/Perfetto trace.
+     *
+     *   const recording = tp.startTrace();
+     *   await work();
+     *   fs.writeFileSync('trace.json', JSON.stringify(recording.stop()));
+     *
+     * Open the file in https://ui.perfetto.dev or chrome://tracing.
+     */
+    startTrace(options = {}) {
+        let unsubscribe = () => undefined;
+        const recorder = createTraceRecorder({ maxRoots: options.maxRoots, onStop: () => unsubscribe() });
+        unsubscribe = this.use(recorder);
+        return recorder;
+    }
+    /** Turn tracking on */
+    enable() {
+        this.config.enabled = true;
+        this.executionTracker.enabled = true;
+        return this;
+    }
+    /** Turn tracking off: tracked functions become plain pass-through calls */
+    disable() {
+        this.config.enabled = false;
+        this.executionTracker.enabled = false;
+        return this;
+    }
+    /** Whether tracking is on */
+    isEnabled() {
+        return this.config.enabled;
     }
     /**
      * Set configuration options
@@ -462,7 +951,25 @@ export class OptimizedPerformanceMonitor {
         }
         // Update sampleRate if specified
         if (config.sampleRate !== undefined) {
-            this.config.sampleRate = Math.max(0, Math.min(1, config.sampleRate));
+            this.config.sampleRate = clampRate(config.sampleRate);
+            this.executionTracker.defaultSampleRate = this.config.sampleRate;
+        }
+        if (config.enabled !== undefined) {
+            this.config.enabled = config.enabled;
+            this.executionTracker.enabled = config.enabled;
+        }
+        if (config.blockingThreshold !== undefined) {
+            this.config.blockingThreshold = config.blockingThreshold;
+            this.executionTracker.blockingThreshold = config.blockingThreshold;
+        }
+        if (config.reporter !== undefined) {
+            this.executionTracker.reporter = config.reporter;
+        }
+        if (config.plugins) {
+            config.plugins.forEach(plugin => this.use(plugin));
+        }
+        if (config.onComplete) {
+            this.onComplete(config.onComplete);
         }
         return { ...this.config };
     }
@@ -494,6 +1001,12 @@ export class OptimizedPerformanceMonitor {
         this.executionTracker.trackingMode = mode;
         return this;
     }
+    /**
+     * Get the current tracking mode
+     */
+    getTrackingMode() {
+        return this.config.trackingMode;
+    }
     /**
      * Enable memory usage tracking
      * @returns This instance for chaining
@@ -518,11 +1031,12 @@ export class OptimizedPerformanceMonitor {
      * @returns This instance for chaining
      */
     setSampleRate(rate) {
-        this.config.sampleRate = Math.max(0, Math.min(1, rate));
+        this.config.sampleRate = clampRate(rate);
+        this.executionTracker.defaultSampleRate = this.config.sampleRate;
         return this;
     }
     /**
-     * Reset the tracker state
+     * Reset the tracker state (in-flight executions and statistics)
      * @returns This instance for chaining
      */
     reset() {
@@ -530,6 +1044,4 @@ export class OptimizedPerformanceMonitor {
         return this;
     }
 }
-// Remove singleton instance to avoid circular dependency - it will be created in index.ts
-// export const optimizedTracePerf = new OptimizedPerformanceMonitor(); 
 //# sourceMappingURL=optimized-performance-monitor.js.map