@camstack/system 1.2.389 → 1.2.391

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

@@ -1,235 +1,235 @@
-import { ProviderRegistration, BaseAddon } from '@camstack/types';
+import type { ConfigUISchema, ProviderRegistration } from "@camstack/types";
+import { 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;
+	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.
- * Settings appear under Cluster → NodeDetail → Settings.
- */
+* Native metrics — CPU, memory, disk usage sampling.
+* Settings appear under Cluster → NodeDetail → Settings.
+*/
 export default class NativeMetricsAddon extends BaseAddon<NativeMetricsConfig> {
-    private provider;
-    private startedAtMs;
-    private snapshotTimer;
-    private processSnapshotTimer;
-    /**
-     * Snapshot-equality cache for the resources + processes emit.
-     * Stores the coarsened JSON and timestamp; a tick where the
-     * coarsened payload matches the cache (and the heartbeat hasn't
-     * elapsed) is skipped.
-     */
-    private lastResourcesEmit;
-    /**
-     * 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 container's OWN memory, sampled on the process-snapshot tick.
-     *
-     * It rides that tick rather than a timer of its own so a memory reading and
-     * the process rows it must be compared against carry the SAME timestamp —
-     * the whole question is a subtraction, and two clocks make it an estimate.
-     * Constructed in `onInitialize`, where the logger exists; it resolves the
-     * cgroup once and latches.
-     */
-    private memoryProbe;
-    private pidsProbe;
-    /** Hot tier for the container reading. Bounds in `container-memory-series.ts`. */
-    private readonly memoryRing;
-    /** Cold tier, HUB only — same reasoning as `loadStore`. */
-    private memoryStore;
-    /** 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;
-    /**
-     * The container's memory over the same window, on the same x-axis.
-     *
-     * Both tiers, merged and deduped on `atMs` like the process series, then
-     * reduced against the SAME `bucketMs` and the SAME origin — otherwise the
-     * two series in one answer would sit on two different axes and the
-     * subtraction they exist for would be an eyeball.
-     *
-     * An EMPTY answer means the node has no cgroup, or nothing has been retained
-     * for it yet. It never means zero.
-     */
-    private readContainerMemory;
-    /**
-     * 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 process-tree timer at the configured interval.
-     *
-     * The process-tree snapshot is FIXED-CADENCE, and its cadence is the
-     * operator's `loadSeriesCadenceSec` (5-60 s, 10 by default).
-     *
-     * It used to emit only ON A CHANGE, with a 60 s fallback heartbeat, and the
-     * dedup is gone rather than tuned. A conditional emit makes a hole in the
-     * series mean two different things — "nothing changed" and "nobody reported"
-     * — and telling those apart is the entire reason an operator opens this chart
-     * after a spike. Now a gap means exactly one thing.
-     *
-     * It is not free: the emit rate is deterministic, so the durable table's row
-     * count is too (nodes x processes / cadence, no discount for a quiet fleet).
-     * The measured cost of that is in `docs/architecture/load-ledger.md`, and it
-     * is why the retention default is six hours rather than three days.
-     */
-    private startProcessSnapshotTimer;
-    /**
-     * Run one periodic tick so that it can NEVER become an unhandled rejection.
-     *
-     * `clearInterval` in `onShutdown` stops FUTURE ticks; it cannot recall one
-     * already in flight. A process tick awaits a `/proc` read and a
-     * `$process.list` broker call, and a graceful stop shuts this addon down
-     * (nulling `ctx`) while the agent goes on to stop its other addons and the
-     * broker — so the tick resumed with no context, its catch block reached for
-     * `this.ctx.logger`, threw again, and the rejection of the timer callback
-     * killed `docker stop CamStack-Agent` with exit code 1 (little-unraid,
-     * 2026-10-07 04:22Z). The ticks themselves now capture their context once
-     * and stand down when it is gone; this wrapper is the backstop.
-     *
-     * A tick before `initialize()` or after `shutdown()` is a no-op.
-     */
-    private runTick;
-    protected onShutdown(): Promise<void>;
-    /**
-     * Resolve this node's short id (strips any `nodeId/addonId` suffix).
-     * Returns null when the provider or event bus isn't available yet.
-     */
-    private resolveSnapshotNodeId;
-    /**
-     * Emit one `metrics.node-resources-snapshot` for this node. Cheap —
-     * reads the cached sample (the provider's background sampler already
-     * runs at samplingIntervalMs). Fires on METRICS_SNAPSHOT_INTERVAL_MS.
-     */
-    private emitResourcesSnapshot;
-    /**
-     * Emit one `metrics.node-processes-snapshot` for this node.
-     *
-     * Heavy — a full process-table read (`/proc` on Linux, `ps -eo` elsewhere;
-     * `proc-process-table.ts`) 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>;
-    private listWorkerInstances;
-    private listAddonInstances;
-    private getAddonStats;
-    /**
-     * Walk the OS process table and classify each camstack-shaped process.
-     *
-     * 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;
-    /**
-     * Every pid + command + resource stats on this node.
-     *
-     * From `/proc` on Linux — no fork. This used to be a `ps -eo` child on every
-     * tick, i.e. a synchronous `fork()` of hub-main at p50 91 ms (D441, D452).
-     * `ps` remains the source only on a platform without `/proc`.
-     */
-    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;
+	private provider;
+	private startedAtMs;
+	private snapshotTimer;
+	private processSnapshotTimer;
+	/**
+	* Snapshot-equality cache for the resources + processes emit.
+	* Stores the coarsened JSON and timestamp; a tick where the
+	* coarsened payload matches the cache (and the heartbeat hasn't
+	* elapsed) is skipped.
+	*/
+	private lastResourcesEmit;
+	/**
+	* 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 container's OWN memory, sampled on the process-snapshot tick.
+	*
+	* It rides that tick rather than a timer of its own so a memory reading and
+	* the process rows it must be compared against carry the SAME timestamp —
+	* the whole question is a subtraction, and two clocks make it an estimate.
+	* Constructed in `onInitialize`, where the logger exists; it resolves the
+	* cgroup once and latches.
+	*/
+	private memoryProbe;
+	private pidsProbe;
+	/** Hot tier for the container reading. Bounds in `container-memory-series.ts`. */
+	private readonly memoryRing;
+	/** Cold tier, HUB only — same reasoning as `loadStore`. */
+	private memoryStore;
+	/** 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;
+	/**
+	* The container's memory over the same window, on the same x-axis.
+	*
+	* Both tiers, merged and deduped on `atMs` like the process series, then
+	* reduced against the SAME `bucketMs` and the SAME origin — otherwise the
+	* two series in one answer would sit on two different axes and the
+	* subtraction they exist for would be an eyeball.
+	*
+	* An EMPTY answer means the node has no cgroup, or nothing has been retained
+	* for it yet. It never means zero.
+	*/
+	private readContainerMemory;
+	/**
+	* 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 process-tree timer at the configured interval.
+	*
+	* The process-tree snapshot is FIXED-CADENCE, and its cadence is the
+	* operator's `loadSeriesCadenceSec` (5-60 s, 10 by default).
+	*
+	* It used to emit only ON A CHANGE, with a 60 s fallback heartbeat, and the
+	* dedup is gone rather than tuned. A conditional emit makes a hole in the
+	* series mean two different things — "nothing changed" and "nobody reported"
+	* — and telling those apart is the entire reason an operator opens this chart
+	* after a spike. Now a gap means exactly one thing.
+	*
+	* It is not free: the emit rate is deterministic, so the durable table's row
+	* count is too (nodes x processes / cadence, no discount for a quiet fleet).
+	* The measured cost of that is in `docs/architecture/load-ledger.md`, and it
+	* is why the retention default is six hours rather than three days.
+	*/
+	private startProcessSnapshotTimer;
+	/**
+	* Run one periodic tick so that it can NEVER become an unhandled rejection.
+	*
+	* `clearInterval` in `onShutdown` stops FUTURE ticks; it cannot recall one
+	* already in flight. A process tick awaits a `/proc` read and a
+	* `$process.list` broker call, and a graceful stop shuts this addon down
+	* (nulling `ctx`) while the agent goes on to stop its other addons and the
+	* broker — so the tick resumed with no context, its catch block reached for
+	* `this.ctx.logger`, threw again, and the rejection of the timer callback
+	* killed `docker stop CamStack-Agent` with exit code 1 (little-unraid,
+	* 2026-10-07 04:22Z). The ticks themselves now capture their context once
+	* and stand down when it is gone; this wrapper is the backstop.
+	*
+	* A tick before `initialize()` or after `shutdown()` is a no-op.
+	*/
+	private runTick;
+	protected onShutdown(): Promise<void>;
+	/**
+	* Resolve this node's short id (strips any `nodeId/addonId` suffix).
+	* Returns null when the provider or event bus isn't available yet.
+	*/
+	private resolveSnapshotNodeId;
+	/**
+	* Emit one `metrics.node-resources-snapshot` for this node. Cheap —
+	* reads the cached sample (the provider's background sampler already
+	* runs at samplingIntervalMs). Fires on METRICS_SNAPSHOT_INTERVAL_MS.
+	*/
+	private emitResourcesSnapshot;
+	/**
+	* Emit one `metrics.node-processes-snapshot` for this node.
+	*
+	* Heavy — a full process-table read (`/proc` on Linux, `ps -eo` elsewhere;
+	* `proc-process-table.ts`) 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>;
+	private listWorkerInstances;
+	private listAddonInstances;
+	private getAddonStats;
+	/**
+	* Walk the OS process table and classify each camstack-shaped process.
+	*
+	* 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;
+	/**
+	* Every pid + command + resource stats on this node.
+	*
+	* From `/proc` on Linux — no fork. This used to be a `ps -eo` child on every
+	* tick, i.e. a synchronous `fork()` of hub-main at p50 91 ms (D441, D452).
+	* `ps` remains the source only on a platform without `/proc`.
+	*/
+	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(): ConfigUISchema;
 }
-export {};