@omnitron-dev/omnitron 0.2.0 → 0.3.0

package/dist/monitoring/event-loop-watch.js

@@ -0,0 +1,179 @@
+/**
+ * EventLoopWatch — when this daemon's event loop stood still, for how long,
+ * and what it was in the middle of.
+ *
+ * Test node, 2026-09-22 21:17:41–51 UTC: the master's heartbeat `ping` went
+ * unanswered for its ten seconds, the master dropped the connection, and a
+ * deployment reading its credentials through that drop configured six apps
+ * with the wrong password. The master's own loop was running — it logged at
+ * 46.2, 49.4 and 50.9 s inside the window — so the silence was the node's,
+ * and nothing on the node could say whether its loop had stopped, or for how
+ * long, or during what. This is that instrument.
+ *
+ * Two measurements, for two questions:
+ *
+ *   - a STALL — the loop not running for longer than `thresholdMs` — is seen
+ *     the moment it runs again, by a timer that notices it fired late, and
+ *     logged then: with the span it covers and the phases in progress. At the
+ *     end of a window the phase would already be the one after;
+ *   - the WINDOW — `monitorEventLoopDelay` over the last `windowMs`: p99 and
+ *     max, reset each window — is kept for health, where the console reads it.
+ *
+ * Not «warn when p99 exceeds a second», which was the first idea. A stall is
+ * ONE sample in that histogram — sampling every 20 ms, a 1.5 s stall is some
+ * seventy-five firings that never happen and one that happens late — so it
+ * moves the maximum and leaves the percentile where it was. Measured: one
+ * 1.5 s stall in a 4.5 s window, 139 samples, p50 22 ms, p99 25.6 ms, max
+ * 1 505.8 ms. A p99 threshold would not have seen the node go quiet.
+ *
+ * The gap is measured on the monotonic clock. A laptop master that sleeps for
+ * an hour has not stalled for an hour, and a wall-clock gap would say it had
+ * on every lid it opened. Wall time is used only to name the moments.
+ *
+ * And each stall says what the PROCESS was doing meanwhile, by the CPU time
+ * it used across the gap — which turns «probably starved» into a reading.
+ * The first live runs logged ten stalls of 1.1–2.0 s on the dev-laptop master,
+ * every one while test suites ran at load 44–73, and the explanation stayed a
+ * guess. Measured on that laptop (16 cores), CPU per wall-clock second:
+ *
+ *     busy-wait on the loop                 0.98   its own work
+ *     Atomics.wait / execSync('sleep 1')    0.00   off the CPU
+ *     busy-wait + a spinning worker thread  1.93   other threads too
+ *
+ * `process.cpuUsage()` counts every thread of the process — worker threads,
+ * GC helpers, the libuv pool — and no child process. So «off the CPU» is
+ * either not being scheduled or WAITING synchronously: a sync spawn's child
+ * does its work on another process's account, which is how the `execSync`
+ * wedge of 2026-09-14 would read here.
+ */
+import { monitorEventLoopDelay, performance } from 'node:perf_hooks';
+import { activePhases } from '../project/deploy-phases.js';
+/**
+ * What the CPU time across a stall says about it. The bounds sit between the
+ * calibration points above: 0.00, 0.98 and 1.93.
+ */
+export function cpuVerdict(cpuMs, stalledMs) {
+    const share = stalledMs > 0 ? cpuMs / stalledMs : 0;
+    if (share < 0.5)
+        return 'off-cpu';
+    if (share <= 1.2)
+        return 'on-cpu';
+    return 'on-cpu-in-parallel';
+}
+/** The verdict in words, with the figure it rests on. */
+export function describeCpu(stall) {
+    if (stall.cpu === 'off-cpu') {
+        return `off the CPU for most of it (${stall.cpuMs} ms of CPU): not scheduled, or waiting synchronously — a sync spawn, sync I/O`;
+    }
+    if (stall.cpu === 'on-cpu') {
+        return `on the CPU for most of it (${stall.cpuMs} ms of CPU): its own synchronous work or a GC pause`;
+    }
+    return `more CPU than wall time (${stall.cpuMs} ms): other threads of this process — GC helpers, workers, the libuv pool — ran alongside`;
+}
+const round = (ms) => Math.round(ms * 10) / 10;
+export class EventLoopWatch {
+    logger;
+    thresholdMs;
+    windowMs;
+    tickMs;
+    phases;
+    histogram = null;
+    ticker = null;
+    windowTimer = null;
+    /** `performance.now()` at the last tick — monotonic, see above. */
+    lastTick = 0;
+    /** `process.cpuUsage()` at the last tick. */
+    lastCpu = { user: 0, system: 0 };
+    windowFrom = 0;
+    lastWindow = null;
+    lastStall = null;
+    longestStall = null;
+    stallCount = 0;
+    constructor(logger, options = {}) {
+        this.logger = logger;
+        this.thresholdMs = options.thresholdMs ?? 1_000;
+        this.windowMs = options.windowMs ?? 10_000;
+        this.tickMs = options.tickMs ?? 100;
+        this.phases = options.phases ?? activePhases;
+    }
+    start() {
+        if (this.ticker)
+            return;
+        this.histogram = monitorEventLoopDelay({ resolution: 20 });
+        this.histogram.enable();
+        this.lastTick = performance.now();
+        this.lastCpu = process.cpuUsage();
+        this.windowFrom = Date.now();
+        this.ticker = setInterval(() => this.tick(), this.tickMs);
+        this.windowTimer = setInterval(() => this.closeWindow(), this.windowMs);
+        // An instrument must never be the reason a process stays up.
+        this.ticker.unref();
+        this.windowTimer.unref();
+    }
+    stop() {
+        if (this.ticker)
+            clearInterval(this.ticker);
+        if (this.windowTimer)
+            clearInterval(this.windowTimer);
+        this.ticker = null;
+        this.windowTimer = null;
+        this.histogram?.disable();
+        this.histogram = null;
+    }
+    /** What health reports: the last window, and the stalls since start. */
+    snapshot() {
+        return {
+            thresholdMs: this.thresholdMs,
+            window: this.lastWindow,
+            stalls: this.stallCount,
+            lastStall: this.lastStall,
+            longestStall: this.longestStall,
+        };
+    }
+    tick() {
+        const now = performance.now();
+        const gap = now - this.lastTick;
+        this.lastTick = now;
+        const cpuNow = process.cpuUsage();
+        const cpuMs = Math.round((cpuNow.user - this.lastCpu.user + cpuNow.system - this.lastCpu.system) / 1000);
+        this.lastCpu = cpuNow;
+        // Late by more than the threshold: the timer's own period is not a stall.
+        if (gap - this.tickMs <= this.thresholdMs)
+            return;
+        const wallNow = Date.now();
+        const stalledMs = Math.round(gap);
+        const stall = {
+            from: new Date(wallNow - gap).toISOString(),
+            to: new Date(wallNow).toISOString(),
+            stalledMs,
+            phases: this.phases(),
+            cpuMs,
+            cpu: cpuVerdict(cpuMs, stalledMs),
+        };
+        this.stallCount += 1;
+        this.lastStall = stall;
+        if (!this.longestStall || stall.stalledMs > this.longestStall.stalledMs)
+            this.longestStall = stall;
+        this.logger.warn({ ...stall, thresholdMs: this.thresholdMs }, 'The event loop stood still — nothing on this daemon ran meanwhile: no RPC answered, no heartbeat returned');
+    }
+    /** Read the window and start the next one. Public for the court, which cannot wait ten seconds. */
+    closeWindow() {
+        const histogram = this.histogram;
+        if (!histogram)
+            return null;
+        const now = Date.now();
+        this.lastWindow = {
+            from: new Date(this.windowFrom).toISOString(),
+            to: new Date(now).toISOString(),
+            p99Ms: round(histogram.percentile(99) / 1e6),
+            maxMs: round(histogram.max / 1e6),
+            samples: histogram.count,
+        };
+        this.windowFrom = now;
+        // Per window, not since start: one stall an hour ago is not this minute's
+        // maximum, and a figure that never falls says nothing after its first rise.
+        histogram.reset();
+        return this.lastWindow;
+    }
+}
+//# sourceMappingURL=event-loop-watch.js.map

package/dist/monitoring/event-loop-watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-loop-watch.js","sourceRoot":"","sources":["../../src/monitoring/event-loop-watch.ts"],"names":[],"mappings":"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"}

package/dist/monitoring/host-disk.d.ts

@@ -0,0 +1,6 @@
+/** Free (available to this user) and total bytes, or null when unreadable. */
+export declare function diskAtHome(home?: string): Promise<{
+    free: number;
+    total: number;
+} | null>;
+//# sourceMappingURL=host-disk.d.ts.map

package/dist/monitoring/host-disk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-disk.d.ts","sourceRoot":"","sources":["../../src/monitoring/host-disk.ts"],"names":[],"mappings":"AAgBA,8EAA8E;AAC9E,wBAAsB,UAAU,CAAC,IAAI,GAAE,MAAsB,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CAQ9G"}

package/dist/monitoring/host-disk.js

@@ -0,0 +1,26 @@
+/**
+ * The host's disk, as omnitron sees it: free and total bytes of the
+ * filesystem that holds OMNITRON_HOME — the release store, the stacks'
+ * volumes and, on a single-disk host, the container engine and the test
+ * runners' temp copies too.
+ *
+ * One reading for `omnitron doctor` and the alert evaluator. It was doctor's
+ * alone, and doctor runs when somebody runs it: the master's disk reached 99%
+ * and stopped the container engine three times (2026-07-01, 09-14, 09-29)
+ * with nobody warned before — the last at 21 GiB free of 1.8 TiB, 112 GB of it
+ * dead vitest copies in ~/.tmp.
+ */
+import fs from 'node:fs';
+import { OMNITRON_HOME } from '../config/defaults.js';
+/** Free (available to this user) and total bytes, or null when unreadable. */
+export async function diskAtHome(home = OMNITRON_HOME) {
+    try {
+        const st = await fs.promises.statfs(home);
+        return { free: st.bavail * st.bsize, total: st.blocks * st.bsize };
+    }
+    catch {
+        // No statfs, or the home does not exist yet. Neither is a disk fault.
+        return null;
+    }
+}
+//# sourceMappingURL=host-disk.js.map

package/dist/monitoring/host-disk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-disk.js","sourceRoot":"","sources":["../../src/monitoring/host-disk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAI,GAAW,aAAa;IAC3D,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC1C,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/monitoring/log-line.d.ts

@@ -0,0 +1,188 @@
+/**
+ * What one line of an application's output says about itself — the single
+ * reading of a log line that every consumer of app output shares.
+ *
+ * There were four readings, one in each consumer, and all four said the same
+ * wrong thing about a line that is not JSON: level `info`, time "now".
+ *
+ *   - `LogManager.parseLine` (the daemon's buffer, read by `omnitron logs`)
+ *   - `LogManager.isErrorOrFatal` (which lines reach `error.log`)
+ *   - `LogCollectorService.ingestPinoLine` (the `logs` table)
+ *   - `commands/logs.ts parseLine` (the file fallback)
+ *
+ * Measured 2026-09-23. paysys wrote pino-pretty. Its `app.log` held 95
+ * «Monero chain has not advanced» records at ERROR and `error.log` held none
+ * of them; in the table all 88 such rows of the last day were `info`. On the
+ * master, the test node's paysys had 3 `error` rows and 1 264 995 `info` rows
+ * in a day, 1 216 292 of them the indented lines of multi-line dumps, each a
+ * row of its own. And the time was stamped when the line was READ: `omnitron
+ * logs paysys -f` printed 26 distinct lines 304 times in 7 seconds, because
+ * every poll re-dated the same lines to the moment of the poll, and `--json
+ * logs -n 200` returned 195 records dated at the query while the lines
+ * themselves said 08:56:19–09:03:02.
+ *
+ * So there is one classifier, and what it reads is:
+ *
+ *   JSON            → parsed as is: its own level, its own time.
+ *   a pino-pretty   → level and time from the header. Three headers are in the
+ *   header             files on this host: `[16:01:57.981] INFO (` — the time
+ *                      of day alone, in the LOCAL zone (pino-pretty's default;
+ *                      beside it, a JSON record of the same instant reads
+ *                      13:01:57.986Z); `[2026-09-23 08:49:07.229] INFO (` —
+ *                      titan's `UTC:yyyy-mm-dd HH:MM:ss.l`, in UTC; and colour
+ *                      codes around the level when the writer thought it had a
+ *                      terminal. An offset, when a header carries one, is used.
+ *   an indented line → the continuation of the record before it, not a
+ *                      record of its own. Measured over the six app logs here:
+ *                      every indented line follows a pino-pretty header or a
+ *                      plain line (a stack under its `Error:`), none follows a
+ *                      JSON line; the longest record is 218 lines, 7 KB.
+ *   anything else   → level `unknown` — not `info`, which is a claim nothing
+ *                      in the line supports — and the time it was CAPTURED,
+ *                      stamped once, when the daemon read it from the pipe.
+ *
+ * Only the daemon can know when it captured a line, so the daemon writes it
+ * down: a record that was not JSON is written to the app's file as a JSON
+ * line of its own (`fileLineOf`) carrying the level and time decided here,
+ * and read back from there as the JSON it now is.
+ */
+/** A level this module can name. Other JSON level strings are kept as written. */
+export type KnownLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/** Pino's numbers for the levels it names — the file and the filters speak these. */
+export declare const LEVEL_RANK: Readonly<Record<KnownLevel, number>>;
+/** The level of a line that says nothing about its level. */
+export declare const UNKNOWN_LEVEL = "unknown";
+/** The rank of a level, or `undefined` for one that has no place in the order. */
+export declare function levelRank(level: string): number | undefined;
+/**
+ * The level a JSON record states.
+ *
+ * A number is pino's, read by its thresholds (35 is `warn`, as pino-pretty
+ * prints it). A string is the writer's own word: one of pino's names is
+ * normalised, anything else is kept as written — «parsed as is» — rather than
+ * turned into a level the writer did not say. No level at all is `unknown`.
+ */
+export declare function levelOf(value: unknown): string;
+/** Colour is for a terminal; in a record it is noise between the letters. */
+export declare function stripAnsi(text: string): string;
+/** How one line reads on its own, before it is joined to anything. */
+export type LineClass = {
+    kind: 'json';
+    level: string;
+    /** Epoch ms the record states, or `null` when it states none. */
+    time: number | null;
+    message: string;
+    data: Record<string, unknown>;
+} | {
+    kind: 'pretty';
+    level: string;
+    time: number;
+    message: string;
+    /** pino-pretty's `(name/pid on host)`, when the header has one. */
+    source?: string;
+} | {
+    kind: 'continuation';
+} | {
+    kind: 'text';
+};
+/** A record: a line, or a header and the lines that continue it. */
+export interface LogRecord {
+    kind: 'json' | 'pretty' | 'text';
+    level: string;
+    /** Epoch ms: the record's own time, or the time it was captured. */
+    time: number;
+    /** False when `time` is the capture (or a neighbour's) time, not the record's own. */
+    timeFromLine: boolean;
+    message: string;
+    /** The parsed fields of a JSON record. */
+    data?: Record<string, unknown>;
+    /** pino-pretty's `(name/pid on host)`. */
+    source?: string;
+    /** A JSON record's line exactly as written — the file keeps it verbatim. */
+    raw?: string;
+    /** Physical lines in the record. */
+    lines: number;
+}
+/**
+ * Read one line.
+ *
+ * `reference` dates a header that carries the time of day alone: the capture
+ * time when the daemon reads a pipe, the next record's time when a file is
+ * read backwards.
+ */
+export declare function classifyLine(line: string, reference: number): LineClass;
+/** The record one line opens, dated by `reference` where the line gives no time. */
+export declare function recordOf(klass: Exclude<LineClass, {
+    kind: 'continuation';
+}>, line: string, reference: number): LogRecord;
+/**
+ * The line a record occupies in an app's log file.
+ *
+ * A JSON record is written exactly as the app wrote it. Anything else is
+ * written as a JSON line of its own — the level this module read (absent when
+ * unknown, so `jq 'select(.level >= 50)'` does not take a string for a number),
+ * the time it decided, the text — because a raw line in a file carries no time
+ * a later reader could recover, and "the time of reading" is the defect this
+ * module exists to end. `format` says what the app actually wrote.
+ */
+export declare function fileLineOf(record: LogRecord): string;
+export interface LineAssemblerOptions {
+    /**
+     * How long a record that may still be continued is held after its last
+     * line. A pino-pretty record is one write; its lines arrive in one read or
+     * a few back to back, so this is a bound on waiting, not a guess at pacing.
+     */
+    idleMs?: number;
+    now?: () => number;
+}
+/**
+ * Joins the lines of a capture into records, in order, per key.
+ *
+ * A JSON line is a whole record and is delivered at once. A header or a plain
+ * line is held until a line that is not its continuation arrives, or until
+ * nothing has arrived for `idleMs` — then delivered with every indented line
+ * after it. The key is what the caller can tell apart; the capture hands the
+ * daemon an app's lines without saying which stream each came from, so that is
+ * the app.
+ */
+export declare class LineAssembler {
+    private readonly deliver;
+    private readonly held;
+    private readonly idleMs;
+    private readonly now;
+    constructor(deliver: (key: string, record: LogRecord) => void, options?: LineAssemblerOptions);
+    push(key: string, line: string): void;
+    /** Deliver every held record now — before a flush, a read, or shutdown. */
+    sealAll(): void;
+    dispose(): void;
+    private continueWith;
+    private hold;
+    private arm;
+    private seal;
+    private emit;
+}
+/**
+ * Joins a file's lines into records while reading it BACKWARDS.
+ *
+ * `omnitron logs` reads a file from its end until it has as many matching
+ * records as were asked for, so it meets a dump's indented lines before their
+ * header. They are kept until the header arrives. Each record is dated by the
+ * one after it where it gives no time of its own — for a time-of-day header,
+ * the latest such instant not after it; for a plain line in a file written
+ * before the daemon recorded capture times, that record's time — and the last
+ * record in the file by the file's modification time. Never by the time of
+ * reading.
+ */
+export declare class BackwardAssembler {
+    private readonly deliver;
+    private pending;
+    private reference;
+    constructor(endReference: number, deliver: (record: LogRecord) => void);
+    /** The line before every line pushed so far. */
+    pushEarlier(line: string): void;
+    /** The start of what was read: indented lines whose header lies before it. */
+    finish(): void;
+    private takePending;
+    private orphan;
+}
+//# sourceMappingURL=log-line.d.ts.map

package/dist/monitoring/log-line.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-line.d.ts","sourceRoot":"","sources":["../../src/monitoring/log-line.ts"],"names":[],"mappings":"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"}