@checkstack/healthcheck-common 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # @checkstack/healthcheck-common
 
+## 0.6.0
+
+### Minor Changes
+
+- 11d2679: Add ability to pause health check configurations globally. When paused, health checks continue to be scheduled but execution is skipped for all systems using that configuration. Users with manage access can pause/resume from the Health Checks config page.
+
+## 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.6.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -28,6 +28,7 @@ export interface HealthCheckConfiguration {
   config: Record<string, unknown>;
   intervalSeconds: number;
   collectors?: CollectorConfigEntry[];
+  paused: boolean;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -58,5 +59,5 @@ export const HEALTH_CHECK_RUN_COMPLETED = createSignal(
     configurationName: z.string(),
     status: z.enum(["healthy", "degraded", "unhealthy"]),
     latencyMs: z.number().optional(),
-  })
+  }),
 );

package/src/rpc-contract.ts

@@ -99,6 +99,22 @@ export const healthCheckContract = {
     .input(z.string())
     .output(z.void()),
 
+  pauseConfiguration: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [healthCheckAccess.configuration.manage],
+  })
+    .input(z.string())
+    .output(z.void()),
+
+  resumeConfiguration: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [healthCheckAccess.configuration.manage],
+  })
+    .input(z.string())
+    .output(z.void()),
+
   // ==========================================================================
   // SYSTEM ASSOCIATION (userType: "authenticated")
   // ==========================================================================
@@ -248,12 +264,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 +287,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(),
 });
@@ -79,6 +81,8 @@ export const HealthCheckConfigurationSchema = z.object({
   intervalSeconds: z.number(),
   /** Optional collector configurations */
   collectors: z.array(CollectorConfigEntrySchema).optional(),
+  /** Whether this configuration is paused (execution skipped for all systems) */
+  paused: z.boolean(),
   createdAt: z.date(),
   updatedAt: z.date(),
 });
@@ -276,7 +280,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>;
+}