@camstack/system 1.2.146 → 1.2.147

package/dist/builtins/native-metrics/native-metrics.addon.d.ts

@@ -1,6 +1,14 @@
 import { ProviderRegistration, BaseAddon } from '@camstack/types';
 interface NativeMetricsConfig {
     readonly samplingIntervalMs: number;
+    /**
+     * Fixed cadence of the process-tree snapshot, in SECONDS. 5-60, refused
+     * outside — `load-series-config.ts` explains why refused and not clamped.
+     */
+    readonly loadSeriesCadenceSec: number;
+    /** How long the durable series is KEPT, in hours. The intention; the row
+     *  cap in `load-series-store.ts` is the guarantee. */
+    readonly loadSeriesRetentionHours: number;
 }
 /**
  * Native metrics — CPU, memory, disk usage sampling.
@@ -18,9 +26,88 @@ export default class NativeMetricsAddon extends BaseAddon<NativeMetricsConfig> {
      * elapsed) is skipped.
      */
     private lastResourcesEmit;
-    private lastProcessesEmit;
+    /**
+     * Holds the previous `/proc/<pid>/task/*` tick counts so each process scan
+     * can turn them into an instantaneous CPU rate split between the process's
+     * own threads and V8's helper pool. Self-bounding — see `ThreadCpuTracker`.
+     */
+    private readonly threadCpu;
+    /**
+     * Retention for the snapshots this addon emits. Fed by SUBSCRIBING to
+     * `metrics.node-processes-snapshot`, never by a second sampler — on the hub
+     * that bus carries every node, so the hub's ring is the cluster's. Bounds and
+     * measured cost live in `node-load-ring.ts`.
+     */
+    private readonly loadRing;
+    /**
+     * The COLD tier, and it exists only on the HUB.
+     *
+     * The table is hub-resident and the hub already hears every node's snapshot
+     * on its bus, so the hub's writer is the cluster's. An agent writing through
+     * the `settings-store` singleton would ship its rows over Moleculer, once
+     * per sample, to reach that very same table.
+     */
+    private loadStore;
+    /** The resolved knobs. Re-resolved on every settings write. */
+    private loadConfig;
+    /**
+     * Process rows seen in each node's most recent snapshot — the OBSERVED
+     * numbers the settings form projects its cost from. A constant here would be
+     * a projection that stops being true the first time the fleet changes.
+     */
+    private readonly observedRowsByNode;
     constructor();
+    /** Is this the hub? The same test every other addon uses (`addon-ai`). */
+    private get isHub();
+    /** Process rows observed across the whole fleet, for the cost projection. */
+    private observedFleetRows;
+    /**
+     * Project a `NodeProcess` onto the series' own row.
+     *
+     * `command`, `ppid`, `pgid`, `nodeId`, `threadCount` and `uptimeSec` are
+     * dropped here, at the single point both tiers pass through, so the hot ring
+     * and the cold table carry the SAME shape and the merged read cannot tell
+     * them apart. `command` in particular is the fattest field in a snapshot and
+     * the same identical string on every runner — the runner id travels in the
+     * environment, not in argv — and nothing that draws this series reads it.
+     */
+    private static toRetained;
     protected onInitialize(): Promise<ProviderRegistration[]>;
+    /**
+     * Retain one arriving snapshot in BOTH tiers.
+     *
+     * The ring is written FIRST and it is the gate: `record` refuses a timestamp
+     * this node has already delivered, and only an accepted sample reaches the
+     * table. That is what makes the append idempotent without a unique index
+     * over two million rows — the composite key it replaces was measured at ~40
+     * bytes per row (`load-series-store.ts`).
+     *
+     * The durable append is fire-and-forget: a storage stall must cost a gap in
+     * the cold window, never a blocked event-bus handler. Every failure logs.
+     */
+    private retainSnapshot;
+    /**
+     * The ONE reader, over both tiers.
+     *
+     * Cold first, hot second, merged and deduped on `atMs` — see
+     * `load-series-reader.ts`. The cold read is bounded in ROWS, because rows
+     * are what a query costs, and the fold + reduction happen HERE rather than
+     * in the browser: six hours at the 10 s cadence is 2 160 snapshots, and
+     * shipping them to a page that will discard most of them is precisely the
+     * cost this subsystem exists to avoid.
+     */
+    private readLoadSeries;
+    /**
+     * Re-resolve the knobs and restate the fixed cadence.
+     *
+     * A REFUSED value (out of 5-60 s, or out of 1-72 h) leaves the previous
+     * configuration in force and says so. Refused, never clamped: storing 10
+     * when the operator typed 2 and reading 10 back is a knob and a readback
+     * agreeing on a value nobody chose.
+     */
+    private applyLoadSeriesConfig;
+    /** (Re)arm the fixed-cadence process-tree timer at the configured interval. */
+    private startProcessSnapshotTimer;
     protected onShutdown(): Promise<void>;
     /**
      * Resolve this node's short id (strips any `nodeId/addonId` suffix).
@@ -34,10 +121,14 @@ export default class NativeMetricsAddon extends BaseAddon<NativeMetricsConfig> {
      */
     private emitResourcesSnapshot;
     /**
-     * Emit one `metrics.node-processes-snapshot` for this node. Heavy —
-     * runs a full OS `ps -eo` scan (`runPs`) plus a `$process.list` broker
-     * call. Fires on the coarser PROCESS_SNAPSHOT_INTERVAL_MS so an idle
-     * node isn't paying a process-table walk every 5s. Skip on failure.
+     * Emit one `metrics.node-processes-snapshot` for this node.
+     *
+     * Heavy — a full OS `ps -eo` scan plus a `$process.list` broker call — and
+     * UNCONDITIONAL. The change-detection that used to guard it is gone: with a
+     * fixed cadence a missing interval means exactly one thing, and that is the
+     * property an operator investigating a spike is actually looking for.
+     *
+     * A failed scan emits nothing, which is the same signal: nobody reported.
      */
     private emitProcessesSnapshot;
     protected onConfigChanged(): Promise<void>;
@@ -47,38 +138,12 @@ export default class NativeMetricsAddon extends BaseAddon<NativeMetricsConfig> {
     /**
      * Walk the OS process table and classify each camstack-shaped process.
      *
-     * Classification (ancestry-driven, NOT pattern-driven):
-     *  - root    — the current node's own pid (`process.pid`).
-     *  - managed — pid is registered in the kernel's `$process.list`
-     *              (forked addon worker spawned by this hub).
-     *  - system  — ancestry walk crosses a SUPERVISOR_BOUNDARY_RE match
-     *              (tsx-watch launcher, agent CLI, concurrently, vite,
-     *              npm exec wrapper). The process belongs to the dev
-     *              tree even if not in `$process.list`. NEVER killable.
-     *  - ghost   — ancestry walk reaches `ppid=1` without crossing any
-     *              supervisor boundary AND the parent isn't visible in
-     *              `ps`. A truly orphaned camstack-shaped process. The
-     *              ONLY classification that's eligible for kill.
-     *
-     * Old pattern-only ghost detection produced false positives: every
-     * monorepo-path process matched CAMSTACK_CMD_RE, ancestry walk
-     * stopping at ppid=hub returned false-positive ghosts whenever a
-     * concurrently sibling sat above hub. Ancestry-driven classification
-     * fixes that.
+     * Classification is IDENTITY-driven: `root` is this pid, `managed` is a pid
+     * the kernel's `$process.list` names, and every other camstack-shaped
+     * process is `system`. The rules — and why there is no longer an ancestry
+     * walk behind them — live in `process-classification.ts`.
      */
     private listNodeProcesses;
-    /**
-     * Send SIGTERM / SIGKILL to a pid. Refuses pids that don't appear in
-     * `listNodeProcesses()` to prevent arbitrary system kills — a dedicated
-     * admin-path for resurrected zombies, not a generic shell replacement.
-     *
-     * `root`-classified pids (the running launcher / agent CLI / hub itself)
-     * are also refused: killing them tears down the whole node and the
-     * operator's intent is almost always to nuke a leaked child, not the
-     * supervisor that keeps the rest alive. Process restart goes through
-     * the dedicated `$process.restart` action, not this kill API.
-     */
-    private killProcess;
     /**
      * Ask the addon's forked runner to write a V8 heap snapshot (SIGUSR2 → the
      * runner's diagnostic handler in addon-runner.ts), for deep per-addon memory
@@ -89,6 +154,24 @@ export default class NativeMetricsAddon extends BaseAddon<NativeMetricsConfig> {
     private dumpHeapSnapshot;
     /** Raw `ps` scan returning every pid + command + resource stats. */
     private runPs;
+    /**
+     * The knobs live HERE, on the document this addon already owns.
+     *
+     * Fields on an existing document, never a method per knob —
+     * `system.getLoggingSettings` / `setLoggingSettings` set that precedent.
+     * They are deliberately NOT in the logging document: that one is about
+     * levels and diagnostic windows, and two documents both claiming a knob is
+     * how this repo has already shipped a switch nobody read.
+     *
+     * Cluster-wide, not per-node: every node must emit on the same cadence or
+     * the fleet's series cannot be laid over each other, and the table is single
+     * and hub-resident, so a per-node retention would be a promise nothing could
+     * keep.
+     *
+     * The cost line is computed from OBSERVED numbers — the nodes and process
+     * counts the cluster is actually reporting — so an operator raising the
+     * retention sees what it costs BEFORE applying it, not afterwards.
+     */
     protected globalSettingsSchema(): import('@camstack/types').ConfigUISchema;
 }
 export {};