@camstack/system 1.2.151 → 1.2.154

package/dist/builtins/native-metrics/container-memory-series.d.ts

@@ -0,0 +1,226 @@
+import { ContainerMemoryPoint, ContainerMemorySnapshot, IScopedLogger, SettingsStoreClient } from '@camstack/types';
+import { LoadSeriesRetention } from './load-series-store.js';
+/**
+ * @durable class=audit owner=metrics-native
+ *   write="one row per NODE per sample, appended by the HUB's `native-metrics`
+ *     off its subscription to `metrics.node-processes-snapshot` — the same
+ *     subscription, the same accepted-sample gate and the same timestamps as
+ *     `metrics:node-load-samples`, so a memory row and the process rows of the
+ *     same instant share an `atMs`. A node with no cgroup writes NOTHING; it
+ *     never writes a zeroed row."
+ *   retention="The operator's `loadSeriesRetentionHours` by age and
+ *     CONTAINER_MEMORY_MAX_ROWS by count, swept in the same pass as the process
+ *     table and through the same bounded page. Losing the table loses the cold
+ *     window only: the ring keeps serving the last hour."
+ */
+export declare const CONTAINER_MEMORY_COLLECTION = "metrics:node-memory-samples";
+/**
+ * Per-node ceiling on the HOT ring, in samples.
+ *
+ * Deliberately the same 180 as the process ring — one hour at the 20 s cadence,
+ * six at the 10 s default's own reckoning — because the two series are read
+ * together and a memory window shorter than the process window would silently
+ * truncate the comparison the pair exists to support.
+ */
+export declare const CONTAINER_MEMORY_SAMPLES_PER_NODE = 180;
+/**
+ * Fleet ceiling on the hot ring, in READINGS.
+ *
+ * One reading per node per sample, so this is simply the per-node ceiling times
+ * the partition ceiling the process ring already declares (16). 2 880 readings
+ * of ten numbers each is well under a megabyte — the bound exists so a runaway
+ * node id space costs a fixed amount, not because the number is large.
+ */
+export declare const CONTAINER_MEMORY_MAX_TOTAL_ROWS: number;
+/**
+ * Hard ceiling on the durable table, in ROWS. The guarantee behind the
+ * retention intention, exactly as `DEFAULT_MAX_ROWS` is for the process table.
+ *
+ * | cadence | retention | rows (3 nodes) |
+ * | --- | --- | --- |
+ * | 10 s | 6 h (default) | 6 480 |
+ * | 5 s | 6 h | 12 960 |
+ * | 5 s | 72 h, 16 nodes | 829 440 — capped here |
+ *
+ * 50 000 rows is 7.7x the shipped default. This row is strictly narrower than
+ * a `metrics:node-load-samples` row — fewer columns, one index, every value an
+ * integer varint — and that one was MEASURED at 87 B/row, so 50 000 rows is
+ * **under 4.2 MiB** with the real figure lower still. It is not a knob: a
+ * guarantee that moves with the hand that raised the intention is not one.
+ */
+export declare const CONTAINER_MEMORY_MAX_ROWS = 50000;
+/** Rows one prune pass may remove. Bounded, never a full scan. */
+export declare const CONTAINER_MEMORY_PRUNE_PAGE_ROWS = 20000;
+export declare const CONTAINER_MEMORY_COLUMNS: readonly [{
+    readonly name: "id";
+    readonly type: "INTEGER";
+    readonly primaryKey: true;
+    readonly notNull: true;
+}, {
+    readonly name: "nodeId";
+    readonly type: "TEXT";
+    readonly notNull: true;
+}, {
+    readonly name: "atMs";
+    readonly type: "INTEGER";
+    readonly notNull: true;
+}, {
+    readonly name: "source";
+    readonly type: "TEXT";
+    readonly notNull: true;
+}, {
+    readonly name: "currentMib";
+    readonly type: "INTEGER";
+    readonly notNull: true;
+}, {
+    readonly name: "limitMib";
+    readonly type: "INTEGER";
+}, {
+    readonly name: "anonMib";
+    readonly type: "INTEGER";
+}, {
+    readonly name: "fileMib";
+    readonly type: "INTEGER";
+}, {
+    readonly name: "shmemMib";
+    readonly type: "INTEGER";
+}, {
+    readonly name: "slabMib";
+    readonly type: "INTEGER";
+}, {
+    readonly name: "gpuShmemMib";
+    readonly type: "INTEGER";
+}];
+export declare const CONTAINER_MEMORY_INDEXES: readonly [{
+    readonly name: "idx_node_memory_node_at";
+    readonly columns: readonly ["nodeId", "atMs"];
+}];
+/** One stored row, in the units the table stores them in. */
+export interface ContainerMemoryRow {
+    readonly nodeId: string;
+    readonly atMs: number;
+    readonly source: string;
+    readonly currentMib: number;
+    readonly limitMib: number | null;
+    readonly anonMib: number | null;
+    readonly fileMib: number | null;
+    readonly shmemMib: number | null;
+    readonly slabMib: number | null;
+    readonly gpuShmemMib: number | null;
+}
+/** The ONE encode. */
+export declare function snapshotToRow(nodeId: string, atMs: number, snapshot: ContainerMemorySnapshot): ContainerMemoryRow;
+/**
+ * The ONE decode. A row whose `source` is not a hierarchy this build knows is
+ * skipped rather than coerced — a stored string that no longer means anything
+ * must not be charted as though it did.
+ */
+export declare function rowToPoint(row: ContainerMemoryRow): ContainerMemoryPoint | null;
+/** Structural validation on read. A malformed row is skipped, never charted. */
+export declare function recordToMemoryRow(data: Record<string, unknown>): ContainerMemoryRow | null;
+export interface ContainerMemoryRingOptions {
+    readonly samplesPerNode?: number;
+    /**
+     * Injectable clock, forwarded to the ring's idle-partition sweep. Tests
+     * drive eviction without sleeping for an hour; production uses `Date.now`.
+     */
+    readonly now?: () => number;
+}
+/**
+ * The HOT tier — a naming adapter over {@link NodeLoadRing}, not a second ring.
+ *
+ * One reading per sample, so the ring's "rows" and its samples are the same
+ * count and its fleet budget is a sample budget. Every bound, the idle sweep
+ * and the monotonic replay gate come from there unchanged.
+ */
+export declare class ContainerMemoryRing {
+    private readonly ring;
+    constructor(options?: ContainerMemoryRingOptions);
+    /** Retain one reading. `false` = a timestamp this node already delivered. */
+    record(nodeId: string, atMs: number, snapshot: ContainerMemorySnapshot): boolean;
+    /**
+     * Read one node's retained readings, oldest-first. `sinceMs` is EXCLUSIVE,
+     * matching every other reader in this subsystem.
+     *
+     * A node nobody has recorded answers EMPTY — which is what "this node has no
+     * cgroup" looks like, and it must stay distinguishable from a zero.
+     */
+    read(nodeId: string, sinceMs?: number): readonly ContainerMemoryPoint[];
+}
+/**
+ * Merge the two tiers and reduce, oldest-first.
+ *
+ * Dedupe is on `atMs` with the HOT copy winning, exactly as the process reader
+ * does: the ring holds the reading as it arrived, the table holds it after the
+ * MiB encode.
+ *
+ * Reduction keeps, for each bucket, the reading with the largest
+ * `currentBytes` — WHOLE, every field from that one sample. A per-field
+ * maximum would synthesise a row whose parts never coexisted (an `anon` peak
+ * and a `file` peak minutes apart, summed into a total that never happened),
+ * and a mean would smear away the spike this series exists to find. `atMs`
+ * becomes the bucket START so the points lie on the same x-axis as the folded
+ * process series, which is the only reason both travel in one answer.
+ *
+ * An empty bucket stays ABSENT — never zero, never carried forward.
+ */
+export declare function reduceContainerMemory(points: readonly ContainerMemoryPoint[], bucketMs: number, origin: number): readonly ContainerMemoryPoint[];
+/** Merge cold + hot on `atMs`, hot wins. Exported because dedup is the
+ *  property worth testing on its own. */
+export declare function mergeContainerMemory(cold: readonly ContainerMemoryPoint[], hot: readonly ContainerMemoryPoint[]): readonly ContainerMemoryPoint[];
+export interface ContainerMemoryStoreDeps {
+    readonly store: SettingsStoreClient;
+    readonly logger: IScopedLogger;
+    readonly now?: () => number;
+    readonly prunePageRows?: number;
+}
+/** What one prune pass did. Returned so a test can assert the bound held. */
+export interface ContainerMemoryPruneOutcome {
+    readonly deletedByAge: number;
+    readonly deletedByCap: number;
+    readonly rowsExamined: number;
+    readonly capBit: boolean;
+}
+/**
+ * The COLD tier. Append-only, bounded, and never the authority on anything the
+ * hot ring can answer.
+ *
+ * Every method is best-effort and says so in the log rather than throwing at
+ * the emitter: a storage hiccup must cost a gap in a chart, never a dropped
+ * snapshot on the bus.
+ */
+export declare class ContainerMemoryStore {
+    private declared;
+    private readonly store;
+    private readonly logger;
+    private readonly nowFn;
+    private readonly prunePageRows;
+    constructor(deps: ContainerMemoryStoreDeps);
+    /** Idempotently declare the collection. `false` when the store refused. */
+    declare(): Promise<boolean>;
+    /** Append ONE reading. */
+    append(nodeId: string, atMs: number, snapshot: ContainerMemorySnapshot): Promise<number>;
+    /** Read one node's cold readings, oldest-first. `sinceMs` is EXCLUSIVE. */
+    read(nodeId: string, sinceMs: number, limitRows: number): Promise<readonly ContainerMemoryPoint[]>;
+    /**
+     * Enforce BOTH bounds, oldest-first, through a bounded page each.
+     *
+     * Not rate-limited here: it is driven by the process store's own prune
+     * cadence, so it runs at most once a minute by construction and a second
+     * timer would be a second thing to get wrong.
+     */
+    prune(nodeIds: readonly string[], retention: LoadSeriesRetention): Promise<ContainerMemoryPruneOutcome | null>;
+    /** Total rows, or `null` when the store could not answer. */
+    count(): Promise<number | null>;
+    /**
+     * Delete this node's oldest rows, at most one page's worth.
+     *
+     * `cutoff === null` means "the oldest rows, whatever their age" — the
+     * row-cap path, which is bounded by `limitRows` instead. Either way the page
+     * is READ FIRST, ordered by the one index, and its last `atMs` becomes the
+     * effective cutoff for a single bounded delete. An unbounded `deleteWhere`
+     * would be one statement and one stalling transaction the first time a
+     * retention is lowered.
+     */
+    private deleteOldestPage;
+}

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

@@ -48,6 +48,20 @@ export default class NativeMetricsAddon extends BaseAddon<NativeMetricsConfig> {
      * 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;
+    /** 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;
     /**
@@ -97,6 +111,18 @@ export default class NativeMetricsAddon extends BaseAddon<NativeMetricsConfig> {
      * 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.
      *