@checkstack/collector-hardware-backend 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @checkstack/collector-hardware-backend
 
+## 0.1.15
+
+### Patch Changes
+
+- Updated dependencies [3dd1914]
+  - @checkstack/backend-api@0.7.0
+
+## 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.15",
   "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,11 +118,13 @@ 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);
-      expect(aggregated.avgLoadAvg1m).toBe(1.5);
+      expect(aggregated.avgUsagePercent.avg).toBe(50);
+      expect(aggregated.maxUsagePercent.max).toBe(75);
+      // (1.0 + 2.0) / 2 = 1.5
+      expect(aggregated.avgLoadAvg1m.avg).toBe(1.5);
     });
   });
 

package/src/collectors/cpu.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeMinMax,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedMinMax,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import { healthResultNumber } from "@checkstack/healthcheck-common";
 import {
@@ -58,38 +64,39 @@ const cpuResultSchema = z.object({
 
 export type CpuResult = z.infer<typeof cpuResultSchema>;
 
-const cpuAggregatedSchema = z.object({
-  avgUsagePercent: healthResultNumber({
+// Aggregated result fields definition
+const cpuAggregatedFields = {
+  avgUsagePercent: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg CPU Usage",
     "x-chart-unit": "%",
   }),
-  maxUsagePercent: healthResultNumber({
+  maxUsagePercent: aggregatedMinMax({
     "x-chart-type": "line",
     "x-chart-label": "Max CPU Usage",
     "x-chart-unit": "%",
   }),
-  avgLoadAvg1m: healthResultNumber({
+  avgLoadAvg1m: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Load (1m)",
   }),
-});
+};
 
-export type CpuAggregatedResult = z.infer<typeof cpuAggregatedSchema>;
+// Type inferred from field definitions
+export type CpuAggregatedResult = InferAggregatedResult<
+  typeof cpuAggregatedFields
+>;
 
 // ============================================================================
 // 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";
@@ -98,7 +105,10 @@ export class CpuCollector
 
   config = new Versioned({ version: 1, schema: cpuConfigSchema });
   result = new Versioned({ version: 1, schema: cpuResultSchema });
-  aggregatedResult = new Versioned({ version: 1, schema: cpuAggregatedSchema });
+  aggregatedResult = new VersionedAggregated({
+    version: 1,
+    fields: cpuAggregatedFields,
+  });
 
   async execute({
     config,
@@ -135,21 +145,22 @@ 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 loads = runs
-      .map((r) => r.metadata?.loadAvg1m)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
     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: mergeAverage(
+        existing?.avgUsagePercent,
+        metadata?.usagePercent,
+      ),
+      maxUsagePercent: mergeMinMax(
+        existing?.maxUsagePercent,
+        metadata?.usagePercent,
+      ),
+      avgLoadAvg1m: mergeAverage(existing?.avgLoadAvg1m, metadata?.loadAvg1m),
     };
   }
 

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,10 +102,11 @@ 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);
+      expect(aggregated.avgUsedPercent.avg).toBe(40);
+      expect(aggregated.maxUsedPercent.max).toBe(50);
     });
   });
 

package/src/collectors/disk.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeMinMax,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedMinMax,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import {
   healthResultNumber,
@@ -64,34 +70,35 @@ const diskResultSchema = z.object({
 
 export type DiskResult = z.infer<typeof diskResultSchema>;
 
-const diskAggregatedSchema = z.object({
-  avgUsedPercent: healthResultNumber({
+// Aggregated result fields definition
+const diskAggregatedFields = {
+  avgUsedPercent: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Disk Usage",
     "x-chart-unit": "%",
   }),
-  maxUsedPercent: healthResultNumber({
+  maxUsedPercent: aggregatedMinMax({
     "x-chart-type": "line",
     "x-chart-label": "Max Disk Usage",
     "x-chart-unit": "%",
   }),
-});
+};
 
-export type DiskAggregatedResult = z.infer<typeof diskAggregatedSchema>;
+// Type inferred from field definitions
+export type DiskAggregatedResult = InferAggregatedResult<
+  typeof diskAggregatedFields
+>;
 
 // ============================================================================
 // 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";
@@ -100,9 +107,9 @@ export class DiskCollector
 
   config = new Versioned({ version: 1, schema: diskConfigSchema });
   result = new Versioned({ version: 1, schema: diskResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: diskAggregatedSchema,
+    fields: diskAggregatedFields,
   });
 
   async execute({
@@ -120,16 +127,21 @@ 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;
 
     return {
-      avgUsedPercent: usedPercents.length > 0 ? this.avg(usedPercents) : 0,
-      maxUsedPercent: usedPercents.length > 0 ? Math.max(...usedPercents) : 0,
+      avgUsedPercent: mergeAverage(
+        existing?.avgUsedPercent,
+        metadata?.usedPercent,
+      ),
+      maxUsedPercent: mergeMinMax(
+        existing?.maxUsedPercent,
+        metadata?.usedPercent,
+      ),
     };
   }
 

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,11 +108,12 @@ 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);
-      expect(aggregated.avgUsedMb).toBe(8000);
+      expect(aggregated.avgUsedPercent.avg).toBe(50);
+      expect(aggregated.maxUsedPercent.max).toBe(75);
+      expect(aggregated.avgUsedMb.avg).toBe(8000);
     });
   });
 

package/src/collectors/memory.ts

@@ -4,6 +4,12 @@ import {
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
+  mergeAverage,
+  mergeMinMax,
+  VersionedAggregated,
+  aggregatedAverage,
+  aggregatedMinMax,
+  type InferAggregatedResult,
 } from "@checkstack/backend-api";
 import { healthResultNumber } from "@checkstack/healthcheck-common";
 import {
@@ -67,39 +73,40 @@ const memoryResultSchema = z.object({
 
 export type MemoryResult = z.infer<typeof memoryResultSchema>;
 
-const memoryAggregatedSchema = z.object({
-  avgUsedPercent: healthResultNumber({
+// Aggregated result fields definition
+const memoryAggregatedFields = {
+  avgUsedPercent: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Memory Usage",
     "x-chart-unit": "%",
   }),
-  maxUsedPercent: healthResultNumber({
+  maxUsedPercent: aggregatedMinMax({
     "x-chart-type": "line",
     "x-chart-label": "Max Memory Usage",
     "x-chart-unit": "%",
   }),
-  avgUsedMb: healthResultNumber({
+  avgUsedMb: aggregatedAverage({
     "x-chart-type": "line",
     "x-chart-label": "Avg Memory Used",
     "x-chart-unit": "MB",
   }),
-});
+};
 
-export type MemoryAggregatedResult = z.infer<typeof memoryAggregatedSchema>;
+// Type inferred from field definitions
+export type MemoryAggregatedResult = InferAggregatedResult<
+  typeof memoryAggregatedFields
+>;
 
 // ============================================================================
 // 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";
@@ -108,9 +115,9 @@ export class MemoryCollector
 
   config = new Versioned({ version: 1, schema: memoryConfigSchema });
   result = new Versioned({ version: 1, schema: memoryResultSchema });
-  aggregatedResult = new Versioned({
+  aggregatedResult = new VersionedAggregated({
     version: 1,
-    schema: memoryAggregatedSchema,
+    fields: memoryAggregatedFields,
   });
 
   async execute({
@@ -140,21 +147,22 @@ 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 usedMbs = runs
-      .map((r) => r.metadata?.usedMb)
-      .filter((v): v is number => typeof v === "number");
+    const metadata = run.metadata;
 
     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: mergeAverage(
+        existing?.avgUsedPercent,
+        metadata?.usedPercent,
+      ),
+      maxUsedPercent: mergeMinMax(
+        existing?.maxUsedPercent,
+        metadata?.usedPercent,
+      ),
+      avgUsedMb: mergeAverage(existing?.avgUsedMb, metadata?.usedMb),
     };
   }