@checkstack/healthcheck-common 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @checkstack/healthcheck-common
 
+## 0.5.0
+
+### Minor Changes
+
+- ac3a4cf: ### Dynamic Bucket Sizing for Health Check Visualization
+
+  Implements industry-standard dynamic bucket sizing for health check data aggregation, following patterns from Grafana/VictoriaMetrics.
+
+  **What changed:**
+
+  - Replaced fixed `bucketSize: "hourly" | "daily" | "auto"` with dynamic `targetPoints` parameter (default: 500)
+  - Bucket interval is now calculated as `(endDate - startDate) / targetPoints` with a minimum of 1 second
+  - Added `bucketIntervalSeconds` to aggregated response and individual buckets
+  - Updated chart components to use dynamic time formatting based on bucket interval
+
+  **Why:**
+
+  - A 24-hour view with 1-second health checks previously returned 86,400+ data points, causing lag
+  - Now returns ~500 data points regardless of timeframe, ensuring consistent chart performance
+  - Charts still preserve visual fidelity through proper aggregation
+
+  **Breaking Change:**
+
+  - `bucketSize` parameter removed from `getAggregatedHistory` and `getDetailedAggregatedHistory` endpoints
+  - Use `targetPoints` instead (defaults to 500 if not specified)
+
+  ***
+
+  ### Collector Aggregated Charts Fix
+
+  Fixed issue where collector auto-charts (like HTTP request response time charts) were not showing in aggregated data mode.
+
+  **What changed:**
+
+  - Added `aggregatedResultSchema` to `CollectorDtoSchema`
+  - Backend now returns collector aggregated schemas via `getCollectors` endpoint
+  - Frontend `useStrategySchemas` hook now merges collector aggregated schemas
+  - Service now calls each collector's `aggregateResult()` when building buckets
+  - Aggregated collector data stored in `aggregatedResult.collectors[uuid]`
+
+  **Why:**
+
+  - Previously only strategy-level aggregated results were computed
+  - Collectors like HTTP Request Collector have their own `aggregateResult` method
+  - Without calling these, fields like `avgResponseTimeMs` and `successRate` were missing from aggregated buckets
+
+- db1f56f: Add ephemeral field stripping to reduce database storage for health checks
+
+  - Added `x-ephemeral` metadata flag to `HealthResultMeta` for marking fields that should not be persisted
+  - All health result factory functions (`healthResultString`, `healthResultNumber`, `healthResultBoolean`, `healthResultArray`, `healthResultJSONPath`) now accept `x-ephemeral`
+  - Added `stripEphemeralFields()` utility to remove ephemeral fields before database storage
+  - Integrated ephemeral field stripping into `queue-executor.ts` for all collector results
+  - HTTP Request collector now explicitly marks `body` as ephemeral
+
+  This significantly reduces database storage for health checks with large response bodies, while still allowing assertions to run against the full response at execution time.
+
+### Patch Changes
+
+- Updated dependencies [db1f56f]
+  - @checkstack/common@0.6.0
+  - @checkstack/signal-common@0.1.4
+
 ## 0.4.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-common",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": {

package/src/rpc-contract.ts

@@ -248,12 +248,15 @@ export const healthCheckContract = {
         configurationId: z.string(),
         startDate: z.date(),
         endDate: z.date(),
-        bucketSize: z.enum(["hourly", "daily", "auto"]),
+        /** Target number of data points (default: 500). Bucket interval is calculated as (endDate - startDate) / targetPoints */
+        targetPoints: z.number().min(10).max(2000).default(500),
       }),
     )
     .output(
       z.object({
         buckets: z.array(AggregatedBucketBaseSchema),
+        /** The calculated bucket interval in seconds */
+        bucketIntervalSeconds: z.number(),
       }),
     ),
 
@@ -268,12 +271,15 @@ export const healthCheckContract = {
         configurationId: z.string(),
         startDate: z.date(),
         endDate: z.date(),
-        bucketSize: z.enum(["hourly", "daily", "auto"]),
+        /** Target number of data points (default: 500). Bucket interval is calculated as (endDate - startDate) / targetPoints */
+        targetPoints: z.number().min(10).max(2000).default(500),
       }),
     )
     .output(
       z.object({
         buckets: z.array(AggregatedBucketSchema),
+        /** The calculated bucket interval in seconds */
+        bucketIntervalSeconds: z.number(),
       }),
     ),
 

package/src/schemas.ts

@@ -32,6 +32,8 @@ export const CollectorDtoSchema = z.object({
   configSchema: z.record(z.string(), z.unknown()),
   /** JSON Schema for per-run result metadata (with chart annotations) */
   resultSchema: z.record(z.string(), z.unknown()),
+  /** JSON Schema for aggregated result metadata (with chart annotations) */
+  aggregatedResultSchema: z.record(z.string(), z.unknown()).optional(),
   /** Whether multiple instances of this collector are allowed per config */
   allowMultiple: z.boolean(),
 });
@@ -276,7 +278,10 @@ export const DEFAULT_RETENTION_CONFIG: RetentionConfig = {
  */
 export const AggregatedBucketBaseSchema = z.object({
   bucketStart: z.date(),
-  bucketSize: z.enum(["hourly", "daily"]),
+  /** @deprecated Use bucketIntervalSeconds instead. Kept for backward compatibility. */
+  bucketSize: z.enum(["hourly", "daily"]).optional(),
+  /** Bucket interval in seconds (e.g., 7 for 7-second buckets) */
+  bucketIntervalSeconds: z.number(),
   runCount: z.number(),
   healthyCount: z.number(),
   degradedCount: z.number(),

package/src/zod-health-result.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import {
+  healthResultSchema,
+  healthResultNumber,
+  healthResultString,
+  healthResultJSONPath,
+  stripEphemeralFields,
+  getHealthResultMeta,
+} from "./zod-health-result";
+
+describe("stripEphemeralFields", () => {
+  it("should strip fields marked with x-ephemeral", () => {
+    const schema = healthResultSchema({
+      statusCode: healthResultNumber({ "x-chart-type": "counter" }),
+      body: healthResultJSONPath({ "x-ephemeral": true }), // Explicitly marked ephemeral
+    });
+
+    const result = {
+      statusCode: 200,
+      body: '{"large":"response body that should not be stored"}',
+    };
+
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual({ statusCode: 200 });
+    expect(stripped).not.toHaveProperty("body");
+  });
+
+  it("should preserve non-ephemeral fields", () => {
+    const schema = healthResultSchema({
+      responseTimeMs: healthResultNumber({ "x-chart-type": "line" }),
+      statusText: healthResultString({ "x-chart-type": "text" }),
+    });
+
+    const result = {
+      responseTimeMs: 150,
+      statusText: "OK",
+    };
+
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual(result);
+  });
+
+  it("should preserve unknown fields like _collectorId", () => {
+    const schema = healthResultSchema({
+      value: healthResultNumber({ "x-chart-type": "counter" }),
+      body: healthResultJSONPath({ "x-ephemeral": true }),
+    });
+
+    const result = {
+      _collectorId: "http.request",
+      _assertionFailed: undefined,
+      value: 42,
+      body: "large body content",
+    };
+
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual({
+      _collectorId: "http.request",
+      _assertionFailed: undefined,
+      value: 42,
+    });
+  });
+
+  it("should return original result for non-ZodObject schemas", () => {
+    const schema = z.string();
+    const result = { foo: "bar" };
+
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual(result);
+  });
+
+  it("should handle empty result objects", () => {
+    const schema = healthResultSchema({
+      body: healthResultJSONPath({ "x-ephemeral": true }),
+    });
+
+    const result = {};
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual({});
+  });
+});
+
+describe("healthResultJSONPath", () => {
+  it("should allow explicitly marking fields as ephemeral", () => {
+    const field = healthResultJSONPath({ "x-ephemeral": true });
+    const meta = getHealthResultMeta(field);
+
+    expect(meta?.["x-ephemeral"]).toBe(true);
+    expect(meta?.["x-jsonpath"]).toBe(true);
+  });
+
+  it("should not be ephemeral by default", () => {
+    const field = healthResultJSONPath({});
+    const meta = getHealthResultMeta(field);
+
+    expect(meta?.["x-ephemeral"]).toBeUndefined();
+    expect(meta?.["x-jsonpath"]).toBe(true);
+  });
+});

package/src/zod-health-result.ts

@@ -86,7 +86,7 @@ export type HealthResultShape = Record<string, HealthResultFieldType>;
  * ```
  */
 export function healthResultSchema<T extends HealthResultShape>(
-  shape: T
+  shape: T,
 ): z.ZodObject<T> {
   return z.object(shape);
 }
@@ -111,7 +111,7 @@ type ChartMeta = Omit<HealthResultMeta, "x-jsonpath">;
  * ```
  */
 export function healthResultString(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodString> {
   const schema = z.string();
   schema.register(healthResultRegistry, meta);
@@ -122,7 +122,7 @@ export function healthResultString(
  * Create a health result number field with typed chart metadata.
  */
 export function healthResultNumber(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodNumber> {
   const schema = z.number();
   schema.register(healthResultRegistry, meta);
@@ -133,7 +133,7 @@ export function healthResultNumber(
  * Create a health result boolean field with typed chart metadata.
  */
 export function healthResultBoolean(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodBoolean> {
   const schema = z.boolean();
   schema.register(healthResultRegistry, meta);
@@ -152,7 +152,7 @@ export function healthResultBoolean(
  * ```
  */
 export function healthResultArray(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodArray<z.ZodString>> {
   const schema = z.array(z.string());
   schema.register(healthResultRegistry, meta);
@@ -173,7 +173,7 @@ export function healthResultArray(
  * ```
  */
 export function healthResultJSONPath(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodString> {
   const schema = z.string();
   schema.register(healthResultRegistry, { ...meta, "x-jsonpath": true });
@@ -213,7 +213,60 @@ function unwrapSchema(schema: z.ZodTypeAny): z.ZodTypeAny {
  * Automatically unwraps Optional/Default/Nullable wrappers.
  */
 export function getHealthResultMeta(
-  schema: z.ZodTypeAny
+  schema: z.ZodTypeAny,
 ): HealthResultMeta | undefined {
   return healthResultRegistry.get(unwrapSchema(schema));
 }
+
+// ============================================================================
+// EPHEMERAL FIELD STRIPPING - For storage optimization
+// ============================================================================
+
+/**
+ * Strip ephemeral fields from a result object before database storage.
+ *
+ * Ephemeral fields (marked with x-ephemeral: true) are used during health check
+ * execution for assertions but should not be persisted to save storage space.
+ * Common example: HTTP response bodies used for JSONPath assertions.
+ *
+ * @param result - The full result object from collector execution
+ * @param schema - The Zod schema with health result metadata
+ * @returns A new object with ephemeral fields removed
+ *
+ * @example
+ * ```typescript
+ * const stripped = stripEphemeralFields(collectorResult.result, collector.result.schema);
+ * // The 'body' field (marked with x-ephemeral) is removed before storage
+ * ```
+ */
+export function stripEphemeralFields<T extends Record<string, unknown>>(
+  result: T,
+  schema: z.ZodTypeAny,
+): Partial<T> {
+  // Handle ZodObject schemas
+  if (!(schema instanceof z.ZodObject)) {
+    return result;
+  }
+
+  const shape = schema.shape as Record<string, z.ZodTypeAny>;
+  const stripped: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(result)) {
+    const fieldSchema = shape[key];
+    if (!fieldSchema) {
+      // Keep unknown fields (e.g., _collectorId, _assertionFailed)
+      stripped[key] = value;
+      continue;
+    }
+
+    const meta = getHealthResultMeta(fieldSchema);
+    if (meta?.["x-ephemeral"]) {
+      // Skip ephemeral fields
+      continue;
+    }
+
+    stripped[key] = value;
+  }
+
+  return stripped as Partial<T>;
+}