traceperf 0.2.0 → 1.3.0

package/dist/esm/core/optimized-performance-monitor.d.ts

@@ -10,11 +10,15 @@
  * 6. Module registration capability
  * 7. Enhanced visualization
  */
+import { ExecutionRecord, TracePerfPlugin } from './records.js';
+import { LabelStats, StatsCollector, StatsOptions } from './stats.js';
+import { TraceRecorder } from './exporters.js';
+import type { ModuleTrackOptions, TrackCallOptions, TrackOptions, TracePerfConfig } from '../types/options.js';
 export declare const TrackingModes: {
-    PERFORMANCE: string;
-    BALANCED: string;
-    DETAILED: string;
-    DEBUG: string;
+    readonly PERFORMANCE: "performance";
+    readonly BALANCED: "balanced";
+    readonly DETAILED: "detailed";
+    readonly DEBUG: "debug";
 };
 /**
  * Get current memory usage with environment detection
@@ -41,6 +45,13 @@ export interface ExecutionTrackerOptions {
     showMemoryUsage?: boolean;
     enableNestedTracking?: boolean;
     threshold?: number;
+    sampleRate?: number;
+    enabled?: boolean;
+    blockingThreshold?: number;
+    stats?: boolean | StatsOptions;
+    reporter?: (root: ExecutionRecord) => void;
+    plugins?: TracePerfPlugin[];
+    asyncLocalStorage?: new () => any;
 }
 /**
  * Interface for timer options
@@ -49,6 +60,11 @@ export interface TimerOptions {
     trackMemory?: boolean;
     captureArgs?: boolean;
     args?: any[];
+    /** Per-execution overrides; fall back to the tracker's current settings */
+    silent?: boolean;
+    trackingMode?: string;
+    /** Minimum duration in milliseconds for this execution to be reported */
+    threshold?: number;
 }
 /**
  * Interface for execution data
@@ -68,6 +84,29 @@ export interface ExecutionData {
     memoryDelta?: number;
     result?: any;
     error?: Error | null;
+    silent?: boolean;
+    trackingMode?: string;
+    threshold?: number;
+    /** Set when the function returned a promise: the end of its synchronous part */
+    syncEndTime?: number;
+}
+/**
+ * Render one captured argument as a short, safe string.
+ * Never throws and never walks large structures in full.
+ */
+export declare const formatArg: (arg: unknown) => string;
+/**
+ * A manually-ended execution, see `startSpan()` / `monitor.start()`
+ */
+export interface Span {
+    /** Execution id ('' when the span is not recorded: disabled or sampled out) */
+    readonly id: string;
+    /** Rename the span before it ends (e.g. once a route is known) */
+    setLabel(label: string): void;
+    /** Run `fn` as part of this span; tracked calls inside become its children */
+    run<R>(fn: () => R): R;
+    /** Finish the span; pass the error if the work failed. Calling twice is a no-op. */
+    end(error?: unknown): void;
 }
 /**
  * Optimized tracker for individual function executions
@@ -76,17 +115,40 @@ export declare class OptimizedExecutionTracker {
     private executionTree;
     private currentExecutionId;
     private activeExecutions;
+    private context;
     showMemoryUsage: boolean;
     enableNestedTracking: boolean;
     silent: boolean;
     trackingMode: string;
     defaultThreshold: number;
-    private _formatters;
+    defaultSampleRate: number;
+    /** When false, tracked functions just call through (no timing at all) */
+    enabled: boolean;
+    /** Sync time (ms) from which detailed output flags event-loop blocking; 0 disables */
+    blockingThreshold: number;
+    /** Replaces console output for reported trees (null = default console tree) */
+    reporter: ((root: ExecutionRecord) => void) | null;
+    /** Per-label statistics (null when disabled) */
+    stats: StatsCollector | null;
+    private plugins;
+    private wrappers;
+    private failedPlugins;
     /**
      * Create a new execution tracker
      * @param options Tracker configuration options
      */
     constructor(options?: ExecutionTrackerOptions);
+    /**
+     * Register a plugin. Returns a function that removes it again.
+     */
+    use(plugin: TracePerfPlugin): () => void;
+    /**
+     * Run `run` inside every plugin's wrap() (first registered = outermost).
+     * A wrap() that throws before calling run is reported once and skipped.
+     */
+    private _wrap;
+    private _pluginFailed;
+    private _callPlugins;
     /**
      * Start timing a function execution
      * @param label Function name or label
@@ -94,7 +156,7 @@ export declare class OptimizedExecutionTracker {
      * @param options Additional options
      * @returns Execution ID
      */
-    startTimer(label: string, parentExecutionId?: string | null, options?: TimerOptions): string;
+    startTimer(label: string, parentExecutionId?: string | null, options?: TimerOptions, args?: ArrayLike<unknown> | undefined): string;
     /**
      * End timing a function execution
      * @param executionId ID of the execution to end
@@ -104,14 +166,25 @@ export declare class OptimizedExecutionTracker {
      */
     endTimer(executionId: string, result?: any, error?: Error | null): ExecutionData | null;
     /**
-     * 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
+     * Drop a finished execution and its finished descendants
+     */
+    private _release;
+    /**
+     * Mark the end of the synchronous part of an execution that returned a promise
      */
-    private _generateExecutionFlowChart;
+    markSyncEnd(executionId: string): void;
+    /**
+     * Convert a finished execution (and its finished children) to a record tree
+     */
+    private _toRecord;
+    /**
+     * Print a finished tree (or hand it to the custom reporter)
+     */
+    private _report;
+    /**
+     * Run one call of `fn` with tracking (shared by createTrackable and track)
+     */
+    private _invoke;
     /**
      * Create a trackable version of a function
      * @param fn Function to track
@@ -119,6 +192,12 @@ export declare class OptimizedExecutionTracker {
      * @returns Tracked version of the function
      */
     createTrackable<T extends (...args: any[]) => any>(fn: T, options?: Record<string, any>): (...args: Parameters<T>) => ReturnType<T>;
+    /**
+     * 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: string, options?: Record<string, any>): Span;
     /**
      * Track a module's methods
      * @param module Module to track
@@ -139,16 +218,11 @@ export declare class OptimizedExecutionTracker {
     reset(): void;
 }
 /**
- * Interface for performance monitor options
+ * @deprecated Use `TracePerfConfig`.
  */
-export interface PerformanceMonitorOptions {
-    trackingMode?: string;
-    silent?: boolean;
-    trackMemory?: boolean;
-    enableNestedTracking?: boolean;
-    threshold?: number;
-    sampleRate?: number;
-}
+export type PerformanceMonitorOptions = TracePerfConfig;
+/** Decorator returned by `traced()`: works as a standard or legacy method decorator */
+export type TracedDecorator = (target: any, context?: any, descriptor?: PropertyDescriptor) => any;
 /**
  * Main performance monitoring interface
  */
@@ -166,21 +240,97 @@ export declare class OptimizedPerformanceMonitor {
      * @param options Tracking options
      * @returns Result of the tracked function
      */
-    track<T>(fn: () => T, options?: Record<string, any>): T;
+    track<T>(fn: () => T, options?: TrackCallOptions): T;
     /**
      * Create a trackable version of a function
      * @param fn The function to track
      * @param options Tracking options
      * @returns Tracked version of the function
      */
-    createTrackable<T extends (...args: any[]) => any>(fn: T, options?: Record<string, any>): (...args: Parameters<T>) => ReturnType<T>;
+    createTrackable<T extends (...args: any[]) => any>(fn: T, options?: TrackOptions): (...args: Parameters<T>) => ReturnType<T>;
     /**
      * Register a module for tracking
      * @param module The module or object containing methods to track
      * @param options Tracking options
      * @returns Modified module with tracked methods
      */
-    registerModule<T extends Record<string, any>>(module: T, options?: Record<string, any>): T;
+    registerModule<T extends Record<string, any>>(module: T, options?: ModuleTrackOptions): T;
+    /**
+     * 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<T extends object>(target: T, options?: ModuleTrackOptions): T;
+    /**
+     * 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?: TrackOptions): TracedDecorator;
+    /**
+     * 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: string, options?: TrackOptions): Span;
+    /**
+     * Register a plugin (exporter, custom sink). Returns an unsubscribe function.
+     */
+    use(plugin: TracePerfPlugin): () => void;
+    /**
+     * Call `listener` with every finished top-level execution tree (even when
+     * silent or below threshold). Returns an unsubscribe function.
+     */
+    onComplete(listener: (root: ExecutionRecord) => void): () => void;
+    /**
+     * 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: number | Record<string, number>, listener: (call: ExecutionRecord, root: ExecutionRecord) => void): () => void;
+    /**
+     * Per-label statistics (ms): count, errors, total, mean, min, max,
+     * p50/p95/p99 and mean self time.
+     */
+    getStats(): Record<string, LabelStats>;
+    getStats(label: string): LabelStats | undefined;
+    /** Clear collected statistics */
+    resetStats(): OptimizedPerformanceMonitor;
+    /** Statistics as a text table, slowest total first */
+    formatStats(): string;
+    /** Print the statistics table to the console */
+    printStats(): OptimizedPerformanceMonitor;
+    /**
+     * 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?: {
+        maxRoots?: number;
+    }): TraceRecorder;
+    /** Turn tracking on */
+    enable(): OptimizedPerformanceMonitor;
+    /** Turn tracking off: tracked functions become plain pass-through calls */
+    disable(): OptimizedPerformanceMonitor;
+    /** Whether tracking is on */
+    isEnabled(): boolean;
     /**
      * Set configuration options
      * @param config Configuration to update
@@ -203,6 +353,10 @@ export declare class OptimizedPerformanceMonitor {
      * @returns This instance for chaining
      */
     setTrackingMode(mode: string): OptimizedPerformanceMonitor;
+    /**
+     * Get the current tracking mode
+     */
+    getTrackingMode(): string;
     /**
      * Enable memory usage tracking
      * @returns This instance for chaining
@@ -220,7 +374,7 @@ export declare class OptimizedPerformanceMonitor {
      */
     setSampleRate(rate: number): OptimizedPerformanceMonitor;
     /**
-     * Reset the tracker state
+     * Reset the tracker state (in-flight executions and statistics)
      * @returns This instance for chaining
      */
     reset(): OptimizedPerformanceMonitor;