@lakutata/monitor 3.0.0-beta.0

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

@@ -0,0 +1,61 @@
+import { PerformanceObserver } from 'node:perf_hooks';
+import { Component } from '@lakutata/core';
+import { IMonitor } from './interfaces/IMonitor.js';
+import { IHttpRequestMonitorStatistics } from './interfaces/IHttpRequestMonitorStatistics.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 declare class HttpRequestMonitor extends Component implements IMonitor<IHttpRequestMonitorStatistics> {
+    #private;
+    /**
+     * 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.
+     */
+    protected readonly observer: PerformanceObserver;
+    /**
+     * 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(): IHttpRequestMonitorStatistics;
+    protected init(): Promise<void>;
+    protected destroy(): Promise<void>;
+    /**
+     * Forget the requests: the count and the statistics restart from 0. Use it to measure a period, such as between
+     * two reports.
+     */
+    reset(): void;
+}

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

@@ -0,0 +1,61 @@
+import { Component } from '@lakutata/core';
+import { IMonitor } from './interfaces/IMonitor.js';
+import { IMemoryMonitorStatistics } from './interfaces/IMemoryMonitorStatistics.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 declare class MemoryMonitor extends Component implements IMonitor<IMemoryMonitorStatistics> {
+    #private;
+    /**
+     * 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(): IMemoryMonitorStatistics;
+    /**
+     * 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
+     */
+    protected sampleMemoryUsage(): void;
+    protected init(): Promise<void>;
+    protected destroy(): Promise<void>;
+    /**
+     * 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(): void;
+}

package/dist/types/monitor/interfaces/ICpuMonitorStatistics.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The statistics of a {@link CpuMonitor}: the CPU usage of the process in percent of one core (100 is one core fully
+ * busy; above 100 with several cores busy), each sample the average over one second, rounded to 5 decimals. The
+ * minimum, maximum, mean and percentiles cover the samples since the monitor was created or reset; the percentiles are
+ * approximate (3 significant digits). All 0 before the first sample.
+ */
+export interface ICpuMonitorStatistics {
+    /**
+     * The CPU usage over the latest second (the latest sample), in percent of one core.
+     */
+    usage: number;
+    /**
+     * The lowest sample, in percent of one core.
+     */
+    usageMin: number;
+    /**
+     * The highest sample, in percent of one core.
+     */
+    usageMax: number;
+    /**
+     * The mean of the samples, in percent of one core.
+     */
+    usageAvg: number;
+    /**
+     * The median sample (50% of the seconds used less), in percent of one core.
+     */
+    usageP50: number;
+    /**
+     * The 90th percentile of the samples (90% of the seconds used less), in percent of one core.
+     */
+    usageP90: number;
+    /**
+     * The 95th percentile of the samples, in percent of one core.
+     */
+    usageP95: number;
+    /**
+     * The 99th percentile of the samples, in percent of one core.
+     */
+    usageP99: number;
+}

package/dist/types/monitor/interfaces/IEventLoopMonitorStatistics.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The statistics of an {@link EventLoopMonitor} since it was created or reset: the event loop delays, in milliseconds
+ * (measured by a timer due every millisecond: about 1 ms when the loop is idle, more while synchronous work blocks
+ * it; all 0 before the first measure), and the loop utilization, in percent. The percentiles
+ * come from Node's histogram.
+ */
+export interface IEventLoopMonitorStatistics {
+    /**
+     * The shortest delay, in milliseconds.
+     */
+    min: number;
+    /**
+     * The longest delay, in milliseconds: the longest the loop was blocked.
+     */
+    max: number;
+    /**
+     * The mean delay, in milliseconds.
+     */
+    avg: number;
+    /**
+     * The standard deviation of the delays, in milliseconds.
+     */
+    stdDev: number;
+    /**
+     * The median delay, in milliseconds.
+     */
+    p50: number;
+    /**
+     * The 90th percentile of the delays (90% were shorter), in milliseconds.
+     */
+    p90: number;
+    /**
+     * The 95th percentile of the delays, in milliseconds.
+     */
+    p95: number;
+    /**
+     * The 99th percentile of the delays, in milliseconds: the usual pick for an alert.
+     */
+    p99: number;
+    /**
+     * The share of the time the event loop was busy running code rather than waiting for I/O, in percent (0 to
+     * 100), since the monitor was created or reset. Not rounded.
+     */
+    utilRate: number;
+}

package/dist/types/monitor/interfaces/IHttpRequestMonitorStatistics.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The statistics of an {@link HttpRequestMonitor} since it was created or reset: the number of HTTP requests received
+ * and their durations, from their arrival to the end of their response, in milliseconds rounded to 2 decimals. The
+ * percentiles are approximate (3 significant digits). All 0 before the first request.
+ */
+export interface IHttpRequestMonitorStatistics {
+    /**
+     * The number of requests received whose response ended.
+     */
+    count: number;
+    /**
+     * The shortest request, in milliseconds.
+     */
+    min: number;
+    /**
+     * The longest request, in milliseconds.
+     */
+    max: number;
+    /**
+     * The mean duration, in milliseconds.
+     */
+    avg: number;
+    /**
+     * The standard deviation of the durations, in milliseconds.
+     */
+    stdDev: number;
+    /**
+     * The median duration, in milliseconds.
+     */
+    p50: number;
+    /**
+     * The 90th percentile of the durations (90% of the requests were faster), in milliseconds.
+     */
+    p90: number;
+    /**
+     * The 95th percentile of the durations, in milliseconds.
+     */
+    p95: number;
+    /**
+     * The 99th percentile of the durations, in milliseconds.
+     */
+    p99: number;
+}

package/dist/types/monitor/interfaces/IMemoryMonitorStatistics.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The statistics of a {@link MemoryMonitor}, in bytes unless stated: the latest sample of the process memory
+ * (`process.memoryUsage()`), and the minimum, maximum, mean and percentiles of the samples taken every second since
+ * the monitor was created or reset (0 after a reset until the next sample). The percentiles are approximate (3
+ * significant digits).
+ */
+export interface IMemoryMonitorStatistics {
+    /**
+     * The total physical memory of the host (`os.totalmem()`), in bytes; under a container, the host's,
+     * not the container's limit.
+     */
+    physicalTotal: number;
+    /**
+     * The resident set size of the process (`rss`) at the latest sample: the physical memory it occupies, in
+     * bytes.
+     */
+    physicalUsed: number;
+    /**
+     * `physicalUsed` as a percentage of `physicalTotal`, rounded to 2 decimals.
+     */
+    physicalUsage: number;
+    /**
+     * The lowest resident set size sampled, in bytes.
+     */
+    physicalUsedMin: number;
+    /**
+     * The highest resident set size sampled, in bytes.
+     */
+    physicalUsedMax: number;
+    /**
+     * The mean resident set size of the samples, in bytes, rounded to 2 decimals.
+     */
+    physicalUsedAvg: number;
+    /**
+     * The median resident set size of the samples, in bytes.
+     */
+    physicalUsedP50: number;
+    /**
+     * The 90th percentile of the resident set size samples, in bytes.
+     */
+    physicalUsedP90: number;
+    /**
+     * The 95th percentile of the resident set size samples, in bytes.
+     */
+    physicalUsedP95: number;
+    /**
+     * The 99th percentile of the resident set size samples, in bytes.
+     */
+    physicalUsedP99: number;
+    /**
+     * The size of the V8 heap reserved by the process at the latest sample, in bytes.
+     */
+    heapTotal: number;
+    /**
+     * The part of the V8 heap occupied by JavaScript objects at the latest sample, in bytes.
+     */
+    heapUsed: number;
+    /**
+     * `heapUsed` as a percentage of `heapTotal`, rounded to 2 decimals. V8 grows the heap as needed, so a
+     * high value alone is not a leak: a leak shows as `heapUsedMin` rising from one reset period to the next.
+     */
+    heapUsage: number;
+    /**
+     * The lowest used heap sampled, in bytes.
+     */
+    heapUsedMin: number;
+    /**
+     * The highest used heap sampled, in bytes.
+     */
+    heapUsedMax: number;
+    /**
+     * The mean used heap of the samples, in bytes, rounded to 2 decimals.
+     */
+    heapUsedAvg: number;
+    /**
+     * The median used heap of the samples, in bytes.
+     */
+    heapUsedP50: number;
+    /**
+     * The 90th percentile of the used heap samples, in bytes.
+     */
+    heapUsedP90: number;
+    /**
+     * The 95th percentile of the used heap samples, in bytes.
+     */
+    heapUsedP95: number;
+    /**
+     * The 99th percentile of the used heap samples, in bytes.
+     */
+    heapUsedP99: number;
+    /**
+     * The memory of the C++ objects bound to JavaScript objects (the `Buffer`s included) at the latest
+     * sample, in bytes.
+     */
+    externalUsed: number;
+    /**
+     * The lowest external memory sampled, in bytes.
+     */
+    externalUsedMin: number;
+    /**
+     * The highest external memory sampled, in bytes.
+     */
+    externalUsedMax: number;
+    /**
+     * The mean external memory of the samples, in bytes, rounded to 2 decimals.
+     */
+    externalUsedAvg: number;
+    /**
+     * The median external memory of the samples, in bytes.
+     */
+    externalUsedP50: number;
+    /**
+     * The 90th percentile of the external memory samples, in bytes.
+     */
+    externalUsedP90: number;
+    /**
+     * The 95th percentile of the external memory samples, in bytes.
+     */
+    externalUsedP95: number;
+    /**
+     * The 99th percentile of the external memory samples, in bytes.
+     */
+    externalUsedP99: number;
+}

package/dist/types/monitor/interfaces/IMonitor.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A monitor: a component exposing the statistics of what it measures.
+ * @typeParam T The type of its statistics.
+ */
+export interface IMonitor<T> {
+    /**
+     * The statistics of the measures, computed at each read.
+     */
+    statistics: T;
+}

package/dist/types/monitor/lib/Samples.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 declare class Samples {
+    #private;
+    protected readonly scale: number;
+    /**
+     * @param scale the factor of the precision of the percentiles (100 keeps 2 decimals)
+     */
+    constructor(scale?: number);
+    /**
+     * Record a sample (a negative value is recorded as 0)
+     * @param value
+     */
+    record(value: number): void;
+    /**
+     * The number of samples
+     */
+    get count(): number;
+    /**
+     * The latest sample, 0 without sample
+     */
+    get latest(): number;
+    /**
+     * The minimum, 0 without sample
+     */
+    get min(): number;
+    /**
+     * The maximum, 0 without sample
+     */
+    get max(): number;
+    /**
+     * The mean, 0 without sample
+     */
+    get mean(): number;
+    /**
+     * The (population) standard deviation, 0 without sample
+     */
+    get stdDev(): number;
+    /**
+     * A percentile, 0 without sample
+     * @param percentile from 0 to 100
+     */
+    percentile(percentile: number): number;
+    /**
+     * Forget the samples
+     */
+    reset(): void;
+}
+/**
+ * Round a number to a number of decimals
+ * @param value
+ * @param fractionDigits
+ * @constructor
+ */
+export declare function round(value: number, fractionDigits: number): number;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@lakutata/monitor",
+  "version": "3.0.0-beta.0",
+  "description": "The monitors of the lakutata framework: the CPU, the memory, the event loop and the HTTP requests of the process, on the histograms of Node.js.",
+  "type": "module",
+  "main": "./dist/cjs/exports/Monitor.js",
+  "types": "./dist/cjs/exports/Monitor.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/exports/Monitor.d.ts",
+        "default": "./dist/esm/exports/Monitor.js"
+      },
+      "require": {
+        "types": "./dist/cjs/exports/Monitor.d.ts",
+        "default": "./dist/cjs/exports/Monitor.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs-pkg": "node ../../scripts/package-build/cjs-package.mjs",
+    "build:js": "npm run build:cjs && npm run build:esm && npm run build:cjs-pkg",
+    "rebuild": "npm run clean && npm run build:js",
+    "compile": "npm run rebuild",
+    "test:unit": "npm run compile && node --test \"dist/esm/tests/*.spec.js\""
+  },
+  "peerDependencies": {
+    "@lakutata/core": "3.0.0-beta.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "!dist/*/tests",
+    "*.md",
+    "LICENSE",
+    "package.json"
+  ]
+}