@checkstack/collector-hardware-backend 0.1.13 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @checkstack/collector-hardware-backend
 
+## 0.1.14
+
+### Patch Changes
+
+- 48c2080: Migrate aggregation from batch to incremental (`mergeResult`)
+
+  ### Breaking Changes (Internal)
+
+  - Replaced `aggregateResult(runs[])` with `mergeResult(existing, run)` interface across all HealthCheckStrategy and CollectorStrategy implementations
+
+  ### New Features
+
+  - Added incremental aggregation utilities in `@checkstack/backend-api`:
+    - `mergeCounter()` - track occurrences
+    - `mergeAverage()` - track sum/count, compute avg
+    - `mergeRate()` - track success/total, compute %
+    - `mergeMinMax()` - track min/max values
+  - Exported Zod schemas for internal state: `averageStateSchema`, `rateStateSchema`, `minMaxStateSchema`, `counterStateSchema`
+
+  ### Improvements
+
+  - Enables O(1) storage overhead by maintaining incremental aggregation state
+  - Prepares for real-time hourly aggregation without batch accumulation
+
+- Updated dependencies [f676e11]
+- Updated dependencies [48c2080]
+  - @checkstack/common@0.6.2
+  - @checkstack/backend-api@0.6.0
+  - @checkstack/healthcheck-common@0.8.2
+  - @checkstack/healthcheck-ssh-common@0.1.8
+
 ## 0.1.13
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/collector-hardware-backend",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {
@@ -10,15 +10,15 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.5.1",
-    "@checkstack/common": "0.6.0",
-    "@checkstack/healthcheck-common": "0.7.0",
-    "@checkstack/healthcheck-ssh-common": "0.1.6"
+    "@checkstack/backend-api": "0.5.2",
+    "@checkstack/common": "0.6.1",
+    "@checkstack/healthcheck-common": "0.8.1",
+    "@checkstack/healthcheck-ssh-common": "0.1.7"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0",
-    "@checkstack/tsconfig": "0.0.2",
-    "@checkstack/scripts": "0.1.0"
+    "@checkstack/tsconfig": "0.0.3",
+    "@checkstack/scripts": "0.1.1"
   }
 }

package/src/collectors/cpu.test.ts

@@ -9,7 +9,7 @@ describe("CpuCollector", () => {
       stat2?: { stdout: string };
       loadavg?: { stdout: string };
       nproc?: { stdout: string };
-    } = {}
+    } = {},
   ): SshTransportClient => {
     let callCount = 0;
     return {
@@ -96,7 +96,7 @@ describe("CpuCollector", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average and max CPU usage", () => {
       const collector = new CpuCollector();
       const runs = [
@@ -118,10 +118,12 @@ describe("CpuCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgUsagePercent).toBe(50);
       expect(aggregated.maxUsagePercent).toBe(75);
+      // (1.0 + 2.0) / 2 = 1.5
       expect(aggregated.avgLoadAvg1m).toBe(1.5);
     });
   });

package/src/collectors/cpu.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeMinMax,
+  averageStateSchema,
+  minMaxStateSchema,
+  type AverageState,
+  type MinMaxState,
 } from "@checkstack/backend-api";
 import { healthResultNumber } from "@checkstack/healthcheck-common";
 import {
@@ -58,7 +64,7 @@ const cpuResultSchema = z.object({
 
 export type CpuResult = z.infer<typeof cpuResultSchema>;
 
-const cpuAggregatedSchema = z.object({
+const cpuAggregatedDisplaySchema = z.object({
   avgUsagePercent: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg CPU Usage",
@@ -75,21 +81,28 @@ const cpuAggregatedSchema = z.object({
   }),
 });
 
+const cpuAggregatedInternalSchema = z.object({
+  _usage: averageStateSchema.optional(),
+  _maxUsage: minMaxStateSchema.optional(),
+  _load: averageStateSchema.optional(),
+});
+
+const cpuAggregatedSchema = cpuAggregatedDisplaySchema.merge(
+  cpuAggregatedInternalSchema,
+);
+
 export type CpuAggregatedResult = z.infer<typeof cpuAggregatedSchema>;
 
 // ============================================================================
 // CPU COLLECTOR
 // ============================================================================
 
-export class CpuCollector
-  implements
-    CollectorStrategy<
-      SshTransportClient,
-      CpuConfig,
-      CpuResult,
-      CpuAggregatedResult
-    >
-{
+export class CpuCollector implements CollectorStrategy<
+  SshTransportClient,
+  CpuConfig,
+  CpuResult,
+  CpuAggregatedResult
+> {
   id = "cpu";
   displayName = "CPU Metrics";
   description = "Collects CPU usage, load averages, and core count via SSH";
@@ -135,21 +148,34 @@ export class CpuCollector
     return { result };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<CpuResult>[]
+  mergeResult(
+    existing: CpuAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<CpuResult>,
   ): CpuAggregatedResult {
-    const usages = runs
-      .map((r) => r.metadata?.usagePercent)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
+
+    const usageState = mergeAverage(
+      existing?._usage as AverageState | undefined,
+      metadata?.usagePercent,
+    );
+
+    const maxUsageState = mergeMinMax(
+      existing?._maxUsage as MinMaxState | undefined,
+      metadata?.usagePercent,
+    );
 
-    const loads = runs
-      .map((r) => r.metadata?.loadAvg1m)
-      .filter((v): v is number => typeof v === "number");
+    const loadState = mergeAverage(
+      existing?._load as AverageState | undefined,
+      metadata?.loadAvg1m,
+    );
 
     return {
-      avgUsagePercent: usages.length > 0 ? this.avg(usages) : 0,
-      maxUsagePercent: usages.length > 0 ? Math.max(...usages) : 0,
-      avgLoadAvg1m: loads.length > 0 ? this.avg(loads) : 0,
+      avgUsagePercent: usageState.avg,
+      maxUsagePercent: maxUsageState.max,
+      avgLoadAvg1m: loadState.avg,
+      _usage: usageState,
+      _maxUsage: maxUsageState,
+      _load: loadState,
     };
   }
 

package/src/collectors/disk.test.ts

@@ -66,7 +66,7 @@ describe("DiskCollector", () => {
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average and max disk usage", () => {
       const collector = new DiskCollector();
       const runs = [
@@ -102,7 +102,8 @@ describe("DiskCollector", () => {
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgUsedPercent).toBe(40);
       expect(aggregated.maxUsedPercent).toBe(50);

package/src/collectors/disk.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeMinMax,
+  averageStateSchema,
+  minMaxStateSchema,
+  type AverageState,
+  type MinMaxState,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -64,7 +70,7 @@ const diskResultSchema = z.object({
 
 export type DiskResult = z.infer<typeof diskResultSchema>;
 
-const diskAggregatedSchema = z.object({
+const diskAggregatedDisplaySchema = z.object({
   avgUsedPercent: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg Disk Usage",
@@ -77,21 +83,27 @@ const diskAggregatedSchema = z.object({
   }),
 });
 
+const diskAggregatedInternalSchema = z.object({
+  _usage: averageStateSchema.optional(),
+  _maxUsage: minMaxStateSchema.optional(),
+});
+
+const diskAggregatedSchema = diskAggregatedDisplaySchema.merge(
+  diskAggregatedInternalSchema,
+);
+
 export type DiskAggregatedResult = z.infer<typeof diskAggregatedSchema>;
 
 // ============================================================================
 // DISK COLLECTOR
 // ============================================================================
 
-export class DiskCollector
-  implements
-    CollectorStrategy<
-      SshTransportClient,
-      DiskConfig,
-      DiskResult,
-      DiskAggregatedResult
-    >
-{
+export class DiskCollector implements CollectorStrategy<
+  SshTransportClient,
+  DiskConfig,
+  DiskResult,
+  DiskAggregatedResult
+> {
   id = "disk";
   displayName = "Disk Metrics";
   description = "Collects disk usage for a specific mount point via SSH";
@@ -120,16 +132,27 @@ export class DiskCollector
     return { result: parsed };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<DiskResult>[]
+  mergeResult(
+    existing: DiskAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<DiskResult>,
   ): DiskAggregatedResult {
-    const usedPercents = runs
-      .map((r) => r.metadata?.usedPercent)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
+
+    const usageState = mergeAverage(
+      existing?._usage as AverageState | undefined,
+      metadata?.usedPercent,
+    );
+
+    const maxUsageState = mergeMinMax(
+      existing?._maxUsage as MinMaxState | undefined,
+      metadata?.usedPercent,
+    );
 
     return {
-      avgUsedPercent: usedPercents.length > 0 ? this.avg(usedPercents) : 0,
-      maxUsedPercent: usedPercents.length > 0 ? Math.max(...usedPercents) : 0,
+      avgUsedPercent: usageState.avg,
+      maxUsedPercent: maxUsageState.max,
+      _usage: usageState,
+      _maxUsage: maxUsageState,
     };
   }
 

package/src/collectors/memory.test.ts

@@ -76,7 +76,7 @@ Swap:          4096         512        3584`
     });
   });
 
-  describe("aggregateResult", () => {
+  describe("mergeResult", () => {
     it("should calculate average and max memory usage", () => {
       const collector = new MemoryCollector();
       const runs = [
@@ -108,7 +108,8 @@ Swap:          4096         512        3584`
         },
       ];
 
-      const aggregated = collector.aggregateResult(runs);
+      let aggregated = collector.mergeResult(undefined, runs[0]);
+      aggregated = collector.mergeResult(aggregated, runs[1]);
 
       expect(aggregated.avgUsedPercent).toBe(50);
       expect(aggregated.maxUsedPercent).toBe(75);

package/src/collectors/memory.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeMinMax,
+  averageStateSchema,
+  minMaxStateSchema,
+  type AverageState,
+  type MinMaxState,
 } from "@checkstack/backend-api";
 import { healthResultNumber } from "@checkstack/healthcheck-common";
 import {
@@ -67,7 +73,7 @@ const memoryResultSchema = z.object({
 
 export type MemoryResult = z.infer<typeof memoryResultSchema>;
 
-const memoryAggregatedSchema = z.object({
+const memoryAggregatedDisplaySchema = z.object({
   avgUsedPercent: healthResultNumber({
     "x-chart-type": "line",
     "x-chart-label": "Avg Memory Usage",
@@ -85,21 +91,28 @@ const memoryAggregatedSchema = z.object({
   }),
 });
 
+const memoryAggregatedInternalSchema = z.object({
+  _usedPercent: averageStateSchema.optional(),
+  _maxUsedPercent: minMaxStateSchema.optional(),
+  _usedMb: averageStateSchema.optional(),
+});
+
+const memoryAggregatedSchema = memoryAggregatedDisplaySchema.merge(
+  memoryAggregatedInternalSchema,
+);
+
 export type MemoryAggregatedResult = z.infer<typeof memoryAggregatedSchema>;
 
 // ============================================================================
 // MEMORY COLLECTOR
 // ============================================================================
 
-export class MemoryCollector
-  implements
-    CollectorStrategy<
-      SshTransportClient,
-      MemoryConfig,
-      MemoryResult,
-      MemoryAggregatedResult
-    >
-{
+export class MemoryCollector implements CollectorStrategy<
+  SshTransportClient,
+  MemoryConfig,
+  MemoryResult,
+  MemoryAggregatedResult
+> {
   id = "memory";
   displayName = "Memory Metrics";
   description = "Collects RAM and swap usage via SSH";
@@ -140,21 +153,34 @@ export class MemoryCollector
     return { result };
   }
 
-  aggregateResult(
-    runs: HealthCheckRunForAggregation<MemoryResult>[]
+  mergeResult(
+    existing: MemoryAggregatedResult | undefined,
+    run: HealthCheckRunForAggregation<MemoryResult>,
   ): MemoryAggregatedResult {
-    const usedPercents = runs
-      .map((r) => r.metadata?.usedPercent)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
+
+    const usedPercentState = mergeAverage(
+      existing?._usedPercent as AverageState | undefined,
+      metadata?.usedPercent,
+    );
+
+    const maxUsedPercentState = mergeMinMax(
+      existing?._maxUsedPercent as MinMaxState | undefined,
+      metadata?.usedPercent,
+    );
 
-    const usedMbs = runs
-      .map((r) => r.metadata?.usedMb)
-      .filter((v): v is number => typeof v === "number");
+    const usedMbState = mergeAverage(
+      existing?._usedMb as AverageState | undefined,
+      metadata?.usedMb,
+    );
 
     return {
-      avgUsedPercent: usedPercents.length > 0 ? this.avg(usedPercents) : 0,
-      maxUsedPercent: usedPercents.length > 0 ? Math.max(...usedPercents) : 0,
-      avgUsedMb: usedMbs.length > 0 ? this.avg(usedMbs) : 0,
+      avgUsedPercent: usedPercentState.avg,
+      maxUsedPercent: maxUsedPercentState.max,
+      avgUsedMb: usedMbState.avg,
+      _usedPercent: usedPercentState,
+      _maxUsedPercent: maxUsedPercentState,
+      _usedMb: usedMbState,
     };
   }