@lakutata/monitor 3.0.0-beta.0

package/dist/esm/exports/Monitor.js

@@ -0,0 +1,9 @@
+export * from '../monitor/CpuMonitor.js';
+export * from '../monitor/EventLoopMonitor.js';
+export * from '../monitor/HttpRequestMonitor.js';
+export * from '../monitor/MemoryMonitor.js';
+export * from '../monitor/interfaces/IMonitor.js';
+export * from '../monitor/interfaces/ICpuMonitorStatistics.js';
+export * from '../monitor/interfaces/IEventLoopMonitorStatistics.js';
+export * from '../monitor/interfaces/IHttpRequestMonitorStatistics.js';
+export * from '../monitor/interfaces/IMemoryMonitorStatistics.js';

package/dist/esm/monitor/CpuMonitor.js

@@ -0,0 +1,92 @@
+import { Component } from '@lakutata/core';
+import { round, Samples } from './lib/Samples.js';
+/**
+ * The CPU monitor: measures the CPU time the process uses (user plus system, all its threads), as a percentage of one
+ * core: 100 is one core fully busy, and a process using several cores (worker threads, the libuv thread pool) goes
+ * above 100. It takes a sample every second, each the average usage over that second, and keeps the statistics of
+ * every sample since it was created or last {@link CpuMonitor.reset}: the latest, the minimum, the maximum, the mean
+ * and percentiles, in constant memory.
+ *
+ * Declare it in the `components` of the application (`{class: CpuMonitor}`) and get it with `@Inject` or
+ * `getObject()`; it is a singleton. It starts sampling when it is created: list it in `bootstrap` to measure from the
+ * launch. The statistics are all 0 until the first sample, one second after its creation. Its timer does not keep the
+ * process alive, and stops when the component is destroyed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {CpuMonitor, type ICpuMonitorStatistics} from 'lakutata/com/monitor'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'cpu.app',
+ *         name: 'Cpu',
+ *         components: {
+ *             cpu: {class: CpuMonitor}
+ *         },
+ *         //Created at the launch, so that it samples from the start
+ *         bootstrap: ['cpu']
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const cpu: CpuMonitor = await app.getObject('cpu')
+ *         setInterval((): void => {
+ *             const statistics: ICpuMonitorStatistics = cpu.statistics
+ *             console.log(`CPU ${statistics.usage}% (p95 ${statistics.usageP95}%, max ${statistics.usageMax}%)`)
+ *         }, 60000)
+ *     })
+ * ```
+ */
+export class CpuMonitor extends Component {
+    #fractionDigits = 5;
+    #intervalDelay = 1000;
+    #samples = new Samples(1e5);
+    #sampleInterval;
+    #previousUsage = process.cpuUsage();
+    #previousTime = process.hrtime.bigint();
+    /**
+     * The statistics of the CPU samples since the monitor was created or reset, computed at each read: the latest
+     * usage and the minimum, maximum, mean and percentiles (P50 to P99) of the samples, in percent of one core, rounded
+     * to 5 decimals. The percentiles are approximate (3 significant digits). All 0 before the first sample.
+     */
+    get statistics() {
+        return {
+            usage: round(this.#samples.latest, this.#fractionDigits),
+            usageMin: round(this.#samples.min, this.#fractionDigits),
+            usageMax: round(this.#samples.max, this.#fractionDigits),
+            usageAvg: round(this.#samples.mean, this.#fractionDigits),
+            usageP50: round(this.#samples.percentile(50), this.#fractionDigits),
+            usageP90: round(this.#samples.percentile(90), this.#fractionDigits),
+            usageP95: round(this.#samples.percentile(95), this.#fractionDigits),
+            usageP99: round(this.#samples.percentile(99), this.#fractionDigits)
+        };
+    }
+    /**
+     * Take a sample: the CPU usage since the previous sample (user plus system time over the elapsed time, in percent of
+     * one core). Called every second.
+     * @protected
+     */
+    sampleCpuUsage() {
+        const now = process.hrtime.bigint();
+        const usage = process.cpuUsage();
+        const cpuMicroseconds = (usage.user - this.#previousUsage.user) + (usage.system - this.#previousUsage.system);
+        const elapsedMicroseconds = Number(now - this.#previousTime) / 1000;
+        this.#previousUsage = usage;
+        this.#previousTime = now;
+        if (elapsedMicroseconds > 0)
+            this.#samples.record(cpuMicroseconds / elapsedMicroseconds * 100);
+    }
+    async init() {
+        this.#previousUsage = process.cpuUsage();
+        this.#previousTime = process.hrtime.bigint();
+        this.#sampleInterval = setInterval(() => this.sampleCpuUsage(), this.#intervalDelay).unref();
+    }
+    async destroy() {
+        clearInterval(this.#sampleInterval);
+    }
+    /**
+     * Forget the samples: the statistics are 0 until the next sample, then cover the samples taken since. Use it to
+     * measure a period, such as between two reports.
+     */
+    reset() {
+        this.#samples.reset();
+    }
+}

package/dist/esm/monitor/EventLoopMonitor.js

@@ -0,0 +1,88 @@
+import { monitorEventLoopDelay, performance } from 'node:perf_hooks';
+import { Component } from '@lakutata/core';
+/**
+ * The event loop monitor: measures how late the event loop of the main thread runs its timers (the event loop delay,
+ * in milliseconds, with Node's `monitorEventLoopDelay` at a 1 ms resolution) and how busy it is (its utilization, in
+ * percent of the time). A growing delay means synchronous work (CPU-bound code, synchronous I/O, large JSON) blocks the
+ * other requests; a utilization near 100 means the loop has no idle time left.
+ *
+ * Both cover the time since the monitor was created or last {@link EventLoopMonitor.reset}: the delays are a
+ * histogram of every measure, the utilization is the share of that whole time the loop was busy. Declare it in the
+ * `components` of the application (`{class: EventLoopMonitor}`) and get it with `@Inject` or `getObject()`; it is a
+ * singleton. It starts measuring when it is created: list it in `bootstrap` to measure from the launch; it stops when
+ * the component is destroyed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {EventLoopMonitor, type IEventLoopMonitorStatistics} from 'lakutata/com/monitor'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'loop.app',
+ *         name: 'Loop',
+ *         components: {
+ *             eventLoop: {class: EventLoopMonitor}
+ *         },
+ *         bootstrap: ['eventLoop']
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const eventLoop: EventLoopMonitor = await app.getObject('eventLoop')
+ *         setInterval((): void => {
+ *             const statistics: IEventLoopMonitorStatistics = eventLoop.statistics
+ *             if (statistics.p99 > 100) console.log(`The event loop lags: p99 ${statistics.p99} ms, ${statistics.utilRate}% busy`)
+ *             //Each report covers the last minute
+ *             eventLoop.reset()
+ *         }, 60000)
+ *     })
+ * ```
+ */
+export class EventLoopMonitor extends Component {
+    constructor() {
+        super(...arguments);
+        /**
+         * The histogram of the event loop delays, in nanoseconds, sampled every millisecond while enabled (from the
+         * monitor's initialization to its destruction).
+         */
+        this.histogram = monitorEventLoopDelay({ resolution: 1 });
+        /**
+         * The event loop utilization when the monitor was created or reset: the start of the period that
+         * {@link IEventLoopMonitorStatistics.utilRate} covers.
+         */
+        this.initUtil = performance.eventLoopUtilization();
+    }
+    /**
+     * The event loop statistics since the monitor was created or reset, computed at each read: the minimum, maximum,
+     * mean, standard deviation and percentiles of the delays in milliseconds (not rounded; all 0 before the first
+     * measure), and the utilization in percent.
+     */
+    get statistics() {
+        //Without sample yet, the histogram gives no meaningful value
+        const sampled = this.histogram.count > 0;
+        const delay = (nanoseconds) => sampled ? nanoseconds / 1e6 : 0;
+        return {
+            min: delay(this.histogram.min),
+            max: delay(this.histogram.max),
+            avg: delay(this.histogram.mean),
+            stdDev: delay(this.histogram.stddev),
+            p50: delay(this.histogram.percentile(50)),
+            p90: delay(this.histogram.percentile(90)),
+            p95: delay(this.histogram.percentile(95)),
+            p99: delay(this.histogram.percentile(99)),
+            utilRate: performance.eventLoopUtilization(this.initUtil).utilization * 100
+        };
+    }
+    async init() {
+        this.histogram.enable();
+    }
+    async destroy() {
+        this.histogram.disable();
+    }
+    /**
+     * Forget the delays and restart the utilization: the statistics then cover the time since this call. Use it to
+     * measure a period, such as between two reports.
+     */
+    reset() {
+        this.histogram.reset();
+        this.initUtil = performance.eventLoopUtilization();
+    }
+}

package/dist/esm/monitor/HttpRequestMonitor.js

@@ -0,0 +1,88 @@
+import { PerformanceObserver } from 'node:perf_hooks';
+import { Component } from '@lakutata/core';
+import { round, Samples } from './lib/Samples.js';
+/**
+ * The HTTP request monitor: measures how long the HTTP requests received by the process take, in milliseconds, from
+ * their arrival to the end of their response, through the performance entries of `node:http` (so every server built on
+ * it is counted: the Express and Fastify adapters, and any other server of the process). The requests the process
+ * sends are not counted, nor are HTTP/2 requests.
+ *
+ * It keeps the count and the statistics of the durations since it was created or last {@link HttpRequestMonitor.reset},
+ * in constant memory. The entries reach it in batches, shortly after the responses end, so a request just answered may
+ * not be counted yet. Declare it in the `components` of the application (`{class: HttpRequestMonitor}`) and get it with
+ * `@Inject` or `getObject()`; it is a singleton. It only sees the requests ending after its creation: list it in
+ * `bootstrap` to measure from the launch; it stops when the component is destroyed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {HttpRequestMonitor, type IHttpRequestMonitorStatistics} from 'lakutata/com/monitor'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'http.app',
+ *         name: 'Http',
+ *         components: {
+ *             httpRequests: {class: HttpRequestMonitor}
+ *         },
+ *         bootstrap: ['httpRequests']
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const httpRequests: HttpRequestMonitor = await app.getObject('httpRequests')
+ *         setInterval((): void => {
+ *             const statistics: IHttpRequestMonitorStatistics = httpRequests.statistics
+ *             console.log(`${statistics.count} requests, avg ${statistics.avg} ms, p99 ${statistics.p99} ms`)
+ *             httpRequests.reset()
+ *         }, 60000)
+ *     })
+ * ```
+ */
+export class HttpRequestMonitor extends Component {
+    constructor() {
+        super(...arguments);
+        this.#fractionDigits = 2;
+        this.#durations = new Samples(100);
+        /**
+         * The observer of the `http` performance entries, recording the duration of each received request (the
+         * `HttpRequest` entries); observing from the monitor's initialization to its destruction.
+         */
+        this.observer = new PerformanceObserver((list) => {
+            //Every request of the batch, the received ones only (HttpClient entries are the requests sent)
+            for (const entry of list.getEntriesByName('HttpRequest'))
+                this.#durations.record(entry.duration);
+        });
+    }
+    #fractionDigits;
+    #durations;
+    /**
+     * The statistics of the request durations since the monitor was created or reset, computed at each read: the
+     * number of requests, and the minimum, maximum, mean, standard deviation and percentiles of their durations in
+     * milliseconds, rounded to 2 decimals. The percentiles are approximate (3 significant digits). All 0 before the first
+     * request.
+     */
+    get statistics() {
+        return {
+            count: this.#durations.count,
+            min: round(this.#durations.min, this.#fractionDigits),
+            max: round(this.#durations.max, this.#fractionDigits),
+            avg: round(this.#durations.mean, this.#fractionDigits),
+            stdDev: round(this.#durations.stdDev, this.#fractionDigits),
+            p50: round(this.#durations.percentile(50), this.#fractionDigits),
+            p90: round(this.#durations.percentile(90), this.#fractionDigits),
+            p95: round(this.#durations.percentile(95), this.#fractionDigits),
+            p99: round(this.#durations.percentile(99), this.#fractionDigits)
+        };
+    }
+    async init() {
+        this.observer.observe({ entryTypes: ['http'] });
+    }
+    async destroy() {
+        this.observer.disconnect();
+    }
+    /**
+     * Forget the requests: the count and the statistics restart from 0. Use it to measure a period, such as between
+     * two reports.
+     */
+    reset() {
+        this.#durations.reset();
+    }
+}

package/dist/esm/monitor/MemoryMonitor.js

@@ -0,0 +1,115 @@
+import * as os from 'node:os';
+import { Component } from '@lakutata/core';
+import { round, Samples } from './lib/Samples.js';
+/**
+ * The memory monitor: measures the memory of the process, in bytes, with `process.memoryUsage()`: its resident set
+ * (the physical memory it occupies, `rss`), its V8 heap (`heapTotal` reserved, `heapUsed` occupied by the JavaScript
+ * objects) and its external memory (the C++ objects bound to JavaScript ones, the `Buffer`s included). It takes a
+ * sample when it is created then every second, and keeps the statistics of every sample since it was created or last
+ * {@link MemoryMonitor.reset}: the minimum, the maximum, the mean and percentiles, in constant memory.
+ *
+ * Declare it in the `components` of the application (`{class: MemoryMonitor}`) and get it with `@Inject` or
+ * `getObject()`; it is a singleton. It starts sampling when it is created: list it in `bootstrap` to measure from the
+ * launch. Its timer does not keep the process alive, and stops when the component is destroyed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {MemoryMonitor, type IMemoryMonitorStatistics} from 'lakutata/com/monitor'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'memory.app',
+ *         name: 'Memory',
+ *         components: {
+ *             memory: {class: MemoryMonitor}
+ *         },
+ *         bootstrap: ['memory']
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const memory: MemoryMonitor = await app.getObject('memory')
+ *         setInterval((): void => {
+ *             const statistics: IMemoryMonitorStatistics = memory.statistics
+ *             const megabytes = (bytes: number): string => (bytes / 1048576).toFixed(1)
+ *             console.log(`RSS ${megabytes(statistics.physicalUsed)} MB (${statistics.physicalUsage}% of the host), heap ${statistics.heapUsage}% used`)
+ *         }, 60000)
+ *     })
+ * ```
+ */
+export class MemoryMonitor extends Component {
+    #fractionDigits = 2;
+    #intervalDelay = 1000;
+    #totalMemorySize = os.totalmem();
+    #physical = new Samples();
+    #heap = new Samples();
+    #external = new Samples();
+    #latest = process.memoryUsage();
+    #sampleInterval;
+    /**
+     * The memory statistics, computed at each read: the latest sample (`physicalUsed`, `heapTotal`, `heapUsed`,
+     * `externalUsed`, in bytes, and the percentages `physicalUsage` and `heapUsage`, rounded to 2 decimals), the host's
+     * total memory, and the minimum, maximum, mean (rounded to 2 decimals) and percentiles of the samples since the
+     * monitor was created or reset. The percentiles are approximate (3 significant digits). The statistics of the
+     * samples are 0 after a reset until the next sample.
+     */
+    get statistics() {
+        const latest = this.#latest;
+        return {
+            physicalTotal: this.#totalMemorySize,
+            physicalUsed: latest.rss,
+            physicalUsage: round(latest.rss / this.#totalMemorySize * 100, this.#fractionDigits),
+            physicalUsedMin: this.#physical.min,
+            physicalUsedMax: this.#physical.max,
+            physicalUsedAvg: round(this.#physical.mean, this.#fractionDigits),
+            physicalUsedP50: this.#physical.percentile(50),
+            physicalUsedP90: this.#physical.percentile(90),
+            physicalUsedP95: this.#physical.percentile(95),
+            physicalUsedP99: this.#physical.percentile(99),
+            heapTotal: latest.heapTotal,
+            heapUsed: latest.heapUsed,
+            heapUsage: round(latest.heapTotal ? latest.heapUsed / latest.heapTotal * 100 : 0, this.#fractionDigits),
+            heapUsedMin: this.#heap.min,
+            heapUsedMax: this.#heap.max,
+            heapUsedAvg: round(this.#heap.mean, this.#fractionDigits),
+            heapUsedP50: this.#heap.percentile(50),
+            heapUsedP90: this.#heap.percentile(90),
+            heapUsedP95: this.#heap.percentile(95),
+            heapUsedP99: this.#heap.percentile(99),
+            externalUsed: latest.external,
+            externalUsedMin: this.#external.min,
+            externalUsedMax: this.#external.max,
+            externalUsedAvg: round(this.#external.mean, this.#fractionDigits),
+            externalUsedP50: this.#external.percentile(50),
+            externalUsedP90: this.#external.percentile(90),
+            externalUsedP95: this.#external.percentile(95),
+            externalUsedP99: this.#external.percentile(99)
+        };
+    }
+    /**
+     * Take a sample of the memory of the process: it becomes the latest usage and is added to the statistics. Called
+     * when the monitor is created, then every second.
+     * @protected
+     */
+    sampleMemoryUsage() {
+        const usage = process.memoryUsage();
+        this.#latest = usage;
+        this.#physical.record(usage.rss);
+        this.#heap.record(usage.heapUsed);
+        this.#external.record(usage.external);
+    }
+    async init() {
+        this.sampleMemoryUsage();
+        this.#sampleInterval = setInterval(() => this.sampleMemoryUsage(), this.#intervalDelay).unref();
+    }
+    async destroy() {
+        clearInterval(this.#sampleInterval);
+    }
+    /**
+     * Forget the samples: the minimum, maximum, mean and percentiles are 0 until the next sample, then cover the samples
+     * taken since. The latest usage is kept.
+     */
+    reset() {
+        this.#physical.reset();
+        this.#heap.reset();
+        this.#external.reset();
+    }
+}

package/dist/esm/monitor/interfaces/ICpuMonitorStatistics.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/monitor/interfaces/IEventLoopMonitorStatistics.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/monitor/interfaces/IHttpRequestMonitorStatistics.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/monitor/interfaces/IMemoryMonitorStatistics.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/monitor/interfaces/IMonitor.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/monitor/lib/Samples.js

@@ -0,0 +1,114 @@
+import { createHistogram } from 'node:perf_hooks';
+/**
+ * The statistics of the samples of a measure, in a constant memory: the latest value, the minimum, the maximum, the
+ * mean and the standard deviation are exact, the percentiles come from a histogram (3 significant digits)
+ */
+export class Samples {
+    /**
+     * The histogram of the percentiles: it records integers from 1, so a value is recorded multiplied by the scale,
+     * plus 1 (a value may be 0)
+     */
+    #histogram = createHistogram();
+    #count = 0;
+    #latest = 0;
+    #min = 0;
+    #max = 0;
+    #mean = 0;
+    //The sum of the squares of the differences from the mean (Welford's algorithm)
+    #m2 = 0;
+    /**
+     * @param scale the factor of the precision of the percentiles (100 keeps 2 decimals)
+     */
+    constructor(scale = 1) {
+        this.scale = scale;
+    }
+    /**
+     * Record a sample (a negative value is recorded as 0)
+     * @param value
+     */
+    record(value) {
+        const sample = Number.isFinite(value) && value > 0 ? value : 0;
+        this.#histogram.record(Math.round(sample * this.scale) + 1);
+        this.#count++;
+        this.#latest = sample;
+        if (this.#count === 1) {
+            this.#min = sample;
+            this.#max = sample;
+        }
+        else {
+            if (sample < this.#min)
+                this.#min = sample;
+            if (sample > this.#max)
+                this.#max = sample;
+        }
+        const delta = sample - this.#mean;
+        this.#mean += delta / this.#count;
+        this.#m2 += delta * (sample - this.#mean);
+    }
+    /**
+     * The number of samples
+     */
+    get count() {
+        return this.#count;
+    }
+    /**
+     * The latest sample, 0 without sample
+     */
+    get latest() {
+        return this.#latest;
+    }
+    /**
+     * The minimum, 0 without sample
+     */
+    get min() {
+        return this.#min;
+    }
+    /**
+     * The maximum, 0 without sample
+     */
+    get max() {
+        return this.#max;
+    }
+    /**
+     * The mean, 0 without sample
+     */
+    get mean() {
+        return this.#mean;
+    }
+    /**
+     * The (population) standard deviation, 0 without sample
+     */
+    get stdDev() {
+        return this.#count ? Math.sqrt(this.#m2 / this.#count) : 0;
+    }
+    /**
+     * A percentile, 0 without sample
+     * @param percentile from 0 to 100
+     */
+    percentile(percentile) {
+        if (!this.#count)
+            return 0;
+        return Math.min(Math.max((this.#histogram.percentile(percentile) - 1) / this.scale, this.#min), this.#max);
+    }
+    /**
+     * Forget the samples
+     */
+    reset() {
+        this.#histogram.reset();
+        this.#count = 0;
+        this.#latest = 0;
+        this.#min = 0;
+        this.#max = 0;
+        this.#mean = 0;
+        this.#m2 = 0;
+    }
+}
+/**
+ * Round a number to a number of decimals
+ * @param value
+ * @param fractionDigits
+ * @constructor
+ */
+export function round(value, fractionDigits) {
+    return parseFloat(value.toFixed(fractionDigits));
+}

package/dist/types/exports/Monitor.d.ts

@@ -0,0 +1,9 @@
+export * from '../monitor/CpuMonitor.js';
+export * from '../monitor/EventLoopMonitor.js';
+export * from '../monitor/HttpRequestMonitor.js';
+export * from '../monitor/MemoryMonitor.js';
+export * from '../monitor/interfaces/IMonitor.js';
+export * from '../monitor/interfaces/ICpuMonitorStatistics.js';
+export * from '../monitor/interfaces/IEventLoopMonitorStatistics.js';
+export * from '../monitor/interfaces/IHttpRequestMonitorStatistics.js';
+export * from '../monitor/interfaces/IMemoryMonitorStatistics.js';

package/dist/types/monitor/CpuMonitor.d.ts

@@ -0,0 +1,60 @@
+import { Component } from '@lakutata/core';
+import { IMonitor } from './interfaces/IMonitor.js';
+import { ICpuMonitorStatistics } from './interfaces/ICpuMonitorStatistics.js';
+/**
+ * The CPU monitor: measures the CPU time the process uses (user plus system, all its threads), as a percentage of one
+ * core: 100 is one core fully busy, and a process using several cores (worker threads, the libuv thread pool) goes
+ * above 100. It takes a sample every second, each the average usage over that second, and keeps the statistics of
+ * every sample since it was created or last {@link CpuMonitor.reset}: the latest, the minimum, the maximum, the mean
+ * and percentiles, in constant memory.
+ *
+ * Declare it in the `components` of the application (`{class: CpuMonitor}`) and get it with `@Inject` or
+ * `getObject()`; it is a singleton. It starts sampling when it is created: list it in `bootstrap` to measure from the
+ * launch. The statistics are all 0 until the first sample, one second after its creation. Its timer does not keep the
+ * process alive, and stops when the component is destroyed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {CpuMonitor, type ICpuMonitorStatistics} from 'lakutata/com/monitor'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'cpu.app',
+ *         name: 'Cpu',
+ *         components: {
+ *             cpu: {class: CpuMonitor}
+ *         },
+ *         //Created at the launch, so that it samples from the start
+ *         bootstrap: ['cpu']
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const cpu: CpuMonitor = await app.getObject('cpu')
+ *         setInterval((): void => {
+ *             const statistics: ICpuMonitorStatistics = cpu.statistics
+ *             console.log(`CPU ${statistics.usage}% (p95 ${statistics.usageP95}%, max ${statistics.usageMax}%)`)
+ *         }, 60000)
+ *     })
+ * ```
+ */
+export declare class CpuMonitor extends Component implements IMonitor<ICpuMonitorStatistics> {
+    #private;
+    /**
+     * The statistics of the CPU samples since the monitor was created or reset, computed at each read: the latest
+     * usage and the minimum, maximum, mean and percentiles (P50 to P99) of the samples, in percent of one core, rounded
+     * to 5 decimals. The percentiles are approximate (3 significant digits). All 0 before the first sample.
+     */
+    get statistics(): ICpuMonitorStatistics;
+    /**
+     * Take a sample: the CPU usage since the previous sample (user plus system time over the elapsed time, in percent of
+     * one core). Called every second.
+     * @protected
+     */
+    protected sampleCpuUsage(): void;
+    protected init(): Promise<void>;
+    protected destroy(): Promise<void>;
+    /**
+     * Forget the samples: the statistics are 0 until the next sample, then cover the samples taken since. Use it to
+     * measure a period, such as between two reports.
+     */
+    reset(): void;
+}

package/dist/types/monitor/EventLoopMonitor.d.ts

@@ -0,0 +1,65 @@
+import { type EventLoopUtilization, type IntervalHistogram } from 'node:perf_hooks';
+import { Component } from '@lakutata/core';
+import { IEventLoopMonitorStatistics } from './interfaces/IEventLoopMonitorStatistics.js';
+import { IMonitor } from './interfaces/IMonitor.js';
+/**
+ * The event loop monitor: measures how late the event loop of the main thread runs its timers (the event loop delay,
+ * in milliseconds, with Node's `monitorEventLoopDelay` at a 1 ms resolution) and how busy it is (its utilization, in
+ * percent of the time). A growing delay means synchronous work (CPU-bound code, synchronous I/O, large JSON) blocks the
+ * other requests; a utilization near 100 means the loop has no idle time left.
+ *
+ * Both cover the time since the monitor was created or last {@link EventLoopMonitor.reset}: the delays are a
+ * histogram of every measure, the utilization is the share of that whole time the loop was busy. Declare it in the
+ * `components` of the application (`{class: EventLoopMonitor}`) and get it with `@Inject` or `getObject()`; it is a
+ * singleton. It starts measuring when it is created: list it in `bootstrap` to measure from the launch; it stops when
+ * the component is destroyed.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {EventLoopMonitor, type IEventLoopMonitorStatistics} from 'lakutata/com/monitor'
+ *
+ * Application
+ *     .run(() => ({
+ *         id: 'loop.app',
+ *         name: 'Loop',
+ *         components: {
+ *             eventLoop: {class: EventLoopMonitor}
+ *         },
+ *         bootstrap: ['eventLoop']
+ *     }))
+ *     .onLaunched(async (app: Application): Promise<void> => {
+ *         const eventLoop: EventLoopMonitor = await app.getObject('eventLoop')
+ *         setInterval((): void => {
+ *             const statistics: IEventLoopMonitorStatistics = eventLoop.statistics
+ *             if (statistics.p99 > 100) console.log(`The event loop lags: p99 ${statistics.p99} ms, ${statistics.utilRate}% busy`)
+ *             //Each report covers the last minute
+ *             eventLoop.reset()
+ *         }, 60000)
+ *     })
+ * ```
+ */
+export declare class EventLoopMonitor extends Component implements IMonitor<IEventLoopMonitorStatistics> {
+    /**
+     * The histogram of the event loop delays, in nanoseconds, sampled every millisecond while enabled (from the
+     * monitor's initialization to its destruction).
+     */
+    protected readonly histogram: IntervalHistogram;
+    /**
+     * The event loop utilization when the monitor was created or reset: the start of the period that
+     * {@link IEventLoopMonitorStatistics.utilRate} covers.
+     */
+    protected initUtil: EventLoopUtilization;
+    /**
+     * The event loop statistics since the monitor was created or reset, computed at each read: the minimum, maximum,
+     * mean, standard deviation and percentiles of the delays in milliseconds (not rounded; all 0 before the first
+     * measure), and the utilization in percent.
+     */
+    get statistics(): IEventLoopMonitorStatistics;
+    protected init(): Promise<void>;
+    protected destroy(): Promise<void>;
+    /**
+     * Forget the delays and restart the utilization: the statistics then cover the time since this call. Use it to
+     * measure a period, such as between two reports.
+     */
+    reset(): void;
+}