@esmj/monitor/dist/index.d.mts

Node.js performance measurement metrics (cpu, memory, event loop, gc)

import { Observer, Observable } from '@esmj/observable';
export { pipe } from '@esmj/observable';

type LinearRegressionInput = number | {
    x: number;
    y: number;
};
type Regression = {
    slope: number;
    yIntercept: number;
    predict: (x?: number) => number;
};
declare function medianNoiseReduction(grouping?: number): (array: number[]) => number[];
declare function linearRegression(): (array: LinearRegressionInput[]) => Regression;
declare function percentile(number?: number): (array: number[]) => number;
declare function takeLast<T = number>(size: number): (array: T[]) => T[];
declare function first<T = number>(): (array: T[]) => T;
declare function last<T = number>(): (array: T[]) => T;
declare function avg(): (array: number[]) => number;
declare function sum(): typeof _sum;
declare function _sum(array: number[]): number;

declare const IS_MEMO: unique symbol;
type MemoizedFunction<T extends (...args: any[]) => any> = {
    (...args: Parameters<T>): ReturnType<T>;
    clear: () => void;
    [IS_MEMO]: true;
};
declare function memo<T extends (...args: any[]) => any>(func: T): MemoizedFunction<T>;

type MonitorOptions = {
    interval?: number;
};
declare class Metric {
    start(_options?: MonitorOptions): void;
    beforeMeasure(_options?: MonitorOptions): void;
    measure(_options?: MonitorOptions): void;
    afterMeasure(_options?: MonitorOptions): void;
    stop(_options?: MonitorOptions): void;
}

declare const requestStart: unique symbol;
type Request$1 = {
    [requestStart]?: number;
    [key: symbol]: unknown;
    on(event: string, callBack: () => void): void;
};
type Response = {
    statusCode?: number;
    on(event: string, callBack: () => void): void;
};
type RequestMetricRequestData = {
    count: {
        total: number;
        active: number;
        zombie: number;
        clientErrors: number;
        serverErrors: number;
        connections: number;
    };
    duration: {
        10: number;
        25: number;
        50: number;
        100: number;
        200: number;
        500: number;
        1000: number;
        2000: number;
        5000: number;
        Infinity: number;
    };
    errorRate: number;
};
declare class RequestMetric extends Metric {
    #private;
    start(): void;
    measure(): {
        request: {
            count: {
                total: number;
                active: number;
                zombie: number;
                clientErrors: number;
                serverErrors: number;
                connections: number;
            };
            duration: {
                10: number;
                25: number;
                50: number;
                100: number;
                200: number;
                500: number;
                1000: number;
                2000: number;
                5000: number;
                Infinity: number;
            };
            errorRate: number;
        };
    };
    afterMeasure(): void;
    stop(): void;
    _createConnection(_message: string): void;
    _createRequest({ request, response, }: {
        request: Request$1;
        response: Response;
    }): void;
    _finishRequest({ request, response, }: {
        request: Request$1;
        response: Response;
    }): void;
}

type MetricsHistoryOptions = {
    limit?: number;
};
type MetricsFunction<T = unknown> = (...args: unknown[]) => T;
interface MetricsHistoryEntry {
    timestamp: number;
    cpuUsage?: {
        user: number;
        system: number;
        percent: number;
    };
    memoryUsage?: {
        percent: number;
        rss: number;
        heapTotal: number;
        heapUsed: number;
        external: number;
        arrayBuffers: number;
    };
    eventLoopDelay?: {
        min: number;
        max: number;
        mean: number;
        stddev: number;
        percentile80: number;
    };
    eventLoopUtilization?: {
        idle: number;
        active: number;
        utilization: number;
    };
    gc?: {
        entry: PerformanceEntry;
    };
    loadAverage?: {
        minute1: number;
        minute5: number;
        minute15: number;
    };
    process?: {
        pid: number;
        ppid: number;
        platform: NodeJS.Platform;
        uptime: number;
        version: string;
    };
    request?: RequestMetricRequestData;
}
interface CustomMetrics {
    getCurrentUtilization?: MemoizedFunction<MetricsFunction<number>>;
    getAverageUtilization?: MemoizedFunction<MetricsFunction<number>>;
    getCurrentMemoryPercent?: MemoizedFunction<MetricsFunction<number>>;
    getAverageMemoryPercent?: MemoizedFunction<MetricsFunction<number>>;
    getEventLoopDelay?: MemoizedFunction<MetricsFunction<number>>;
    getAverageEventLoopDelay?: MemoizedFunction<MetricsFunction<number>>;
    getRequestsActiveCountsTrend?: MemoizedFunction<MetricsFunction<Regression>>;
    getRequestsDurationsTrend?: MemoizedFunction<MetricsFunction<Regression>>;
    [key: string]: MemoizedFunction<MetricsFunction>;
}
declare class MetricsHistory extends Observer {
    #private;
    custom: CustomMetrics;
    percentileMemo: MemoizedFunction<(key: keyof MetricsHistoryEntry, number: number) => number>;
    trendMemo: MemoizedFunction<(key: keyof MetricsHistoryEntry, limit: number) => Regression>;
    constructor(options?: MetricsHistoryOptions);
    get size(): number;
    get current(): MetricsHistoryEntry;
    complete(): void;
    next(metric: MetricsHistoryEntry): void;
    error(error: unknown): void;
    add(name: string, func: MemoizedFunction<MetricsFunction>): void;
    percentile(key: keyof MetricsHistoryEntry, number: number): number;
    trend(key: keyof MetricsHistoryEntry, limit: number): Regression;
    from(key: string): () => any[];
    getValues(key: string): any[];
}

declare class Monitor extends Observable {
    #private;
    constructor(options?: MonitorOptions);
    add(metric: Metric): () => void;
    remove(metric: Metric): void;
    start(): void;
    stop(): void;
}

declare const SEVERITY_LEVEL: Readonly<{
    NORMAL: "normal";
    LOW: "low";
    MEDIUM: "medium";
    HIGH: "high";
    CRITICAL: "critical";
    FATAL: "fatal";
}>;
type SeverityLevel = (typeof SEVERITY_LEVEL)[keyof typeof SEVERITY_LEVEL];
type SeverityOptions = {
    threshold?: {
        denialOfService?: number;
        distributedDenialOfService?: number;
        deadlock?: number;
        oldDataToFatalTime?: number;
    };
    experimental?: {
        evaluateMemoryUsage?: boolean;
    };
};
type SeverityRecord = {
    score: number;
    metric: string;
};
type SeverityCalculation = {
    score: number;
    level: SeverityLevel;
    records: SeverityRecord[];
};
declare class Severity {
    #private;
    constructor(monitor: Monitor, metricsHistory: MetricsHistory, shortMonitor: Monitor, shortMetricsHistory: MetricsHistory, requestMetric: RequestMetric, shortRequestMetric: RequestMetric, options?: SeverityOptions);
    init(): void;
    getThreats(req?: Request): SeverityCalculation;
}

declare function isSeverityLevelAtLeast(threats: SeverityCalculation, minLevel: SeverityLevel): boolean;

declare class CPUUsageMetric extends Metric {
    #private;
    start(): void;
    measure({ interval }: MonitorOptions): {
        cpuUsage: {
            user: number;
            system: number;
            percent: number;
        };
    };
    afterMeasure(): void;
    stop(): void;
}

declare class EventLoopDelayMetric extends Metric {
    #private;
    start(): void;
    beforeMeasure(): void;
    measure({ interval }: MonitorOptions): {
        eventLoopDelay: {
            min: number;
            max: number;
            mean: number;
            stddev: number;
            percentile80: number;
        };
    };
    afterMeasure(): void;
    stop(): void;
}

declare class EventLoopUtilizationMetric extends Metric {
    #private;
    start(): void;
    beforeMeasure(): void;
    measure(): {
        eventLoopUtilization: {
            idle: number;
            active: number;
            utilization: number;
        };
    };
    afterMeasure(): void;
    stop(): void;
}

declare class GCMetric extends Metric {
    #private;
    start(): void;
    measure(): {
        gc: {
            entry: PerformanceEntry;
        };
    };
    afterMeasure(): void;
    stop(): void;
}

declare class LoadAverageMetric extends Metric {
    measure(): {
        loadAverage: {
            minute1: number;
            minute5: number;
            minute15: number;
        };
    };
}

declare class MemoryUsageMetric extends Metric {
    #private;
    start(): void;
    measure(): {
        memoryUsage: {
            percent: number;
            rss: number;
            heapTotal: number;
            heapUsed: number;
            external: number;
            arrayBuffers: number;
        };
    };
    stop(): void;
}

declare class ProcessMetric extends Metric {
    measure(): {
        process: {
            pid: number;
            ppid: number;
            platform: NodeJS.Platform;
            uptime: number;
            version: string;
        };
    };
}

type MonitoringOptions = {
    monitor: MonitorOptions;
    metricsHistory: MetricsHistoryOptions;
    shortMonitor: MonitorOptions;
    shortMetricsHistory: MetricsHistoryOptions;
    severity: SeverityOptions;
};
declare function createMonitoring(options: MonitoringOptions): {
    monitor: Monitor;
    metricsHistory: MetricsHistory;
    shortMonitor: Monitor;
    shortMetricsHistory: MetricsHistory;
    severity: Severity;
    start(): void;
    stop(): void;
};

export { CPUUsageMetric, type CustomMetrics, EventLoopDelayMetric, EventLoopUtilizationMetric, GCMetric, LoadAverageMetric, type MemoizedFunction, MemoryUsageMetric, Metric, type MetricsFunction, MetricsHistory, type MetricsHistoryEntry, Monitor, ProcessMetric, RequestMetric, SEVERITY_LEVEL, Severity, type SeverityCalculation, type SeverityLevel, avg, createMonitoring, first, isSeverityLevelAtLeast, last, linearRegression, medianNoiseReduction, memo, percentile, sum, takeLast };