@oneuptime/common 12.0.2 → 12.0.4

package/Tests/Types/Monitor/IotAlertTemplates.test.ts

@@ -0,0 +1,320 @@
+import {
+  IoTAlertTemplate,
+  IoTAlertTemplateArgs,
+  IoTAlertTemplateCategory,
+  getAllIoTAlertTemplates,
+  getIoTAlertTemplateById,
+  getIoTAlertTemplatesByCategory,
+} from "../../../Types/Monitor/IotAlertTemplates";
+import MonitorStep from "../../../Types/Monitor/MonitorStep";
+import MonitorStepIoTMonitor from "../../../Types/Monitor/MonitorStepIoTMonitor";
+import MetricsAggregationType from "../../../Types/Metrics/MetricsAggregationType";
+import {
+  FilterType,
+  NoDataPolicy,
+} from "../../../Types/Monitor/CriteriaFilter";
+import ObjectID from "../../../Types/ObjectID";
+
+/*
+ * The IoT templates carry two decisions the container templates don't, and
+ * both are the point of this suite:
+ *
+ *   1. INVERTED thresholds. "Bad" for a device is a value that is too LOW —
+ *      no heartbeat (iot_device_up < 1), a draining battery (< 20%), a fading
+ *      radio (< -100 dBm). So the unhealthy criterion is `<` and the healthy
+ *      one is `>=`, the opposite direction from a CPU/memory ceiling. A
+ *      copy-paste of a `>`/`<=` pair from the ceiling templates would make the
+ *      monitor alert exactly when the device is fine. Temperature and CPU are
+ *      genuine ceilings and keep the `>`/`<=` direction — the mix is what makes
+ *      pinning each direction per template worthwhile.
+ *
+ *   2. Per-device grouping. Every template groups by the `device.id` datapoint
+ *      label (NOT `resource.`-prefixed — it is a datapoint attribute, not a
+ *      resource attribute) so one incident fires per device rather than one
+ *      collapsed series for the whole fleet.
+ *
+ *   3. The Device Offline template — and ONLY it — opts into TreatAsZero so a
+ *      registered device that goes completely silent (an empty series) folds
+ *      to 0 and trips `Min(iot_device_up) < 1`. Enabling that on a battery or
+ *      temperature threshold would false-alarm for any silent device, so the
+ *      other templates must NOT carry it.
+ */
+
+interface IoTTemplateCase {
+  id: string;
+  category: IoTAlertTemplateCategory;
+  severity: "Critical" | "Warning";
+  metricName: string;
+  metricAlias: string;
+  aggregation: MetricsAggregationType;
+  offlineFilterType: FilterType;
+  onlineFilterType: FilterType;
+  threshold: number;
+  treatNoDataAsZero: boolean;
+}
+
+const IOT_TEMPLATES: Array<IoTTemplateCase> = [
+  {
+    id: "iot-device-offline",
+    category: "Availability",
+    severity: "Critical",
+    metricName: "iot_device_up",
+    metricAlias: "device_up",
+    // Min: a single down push in the window must win over healthy pushes.
+    aggregation: MetricsAggregationType.Min,
+    offlineFilterType: FilterType.LessThan,
+    onlineFilterType: FilterType.GreaterThanOrEqualTo,
+    threshold: 1,
+    treatNoDataAsZero: true,
+  },
+  {
+    id: "iot-low-battery",
+    category: "Power",
+    severity: "Warning",
+    metricName: "iot_battery_percent",
+    metricAlias: "battery_percent",
+    aggregation: MetricsAggregationType.Avg,
+    offlineFilterType: FilterType.LessThan,
+    onlineFilterType: FilterType.GreaterThanOrEqualTo,
+    threshold: 20,
+    treatNoDataAsZero: false,
+  },
+  {
+    id: "iot-weak-signal",
+    category: "Connectivity",
+    severity: "Warning",
+    metricName: "iot_signal_strength_dbm",
+    metricAlias: "signal_strength",
+    aggregation: MetricsAggregationType.Avg,
+    offlineFilterType: FilterType.LessThan,
+    onlineFilterType: FilterType.GreaterThanOrEqualTo,
+    // dBm is negative; -100 is a real threshold, not a placeholder.
+    threshold: -100,
+    treatNoDataAsZero: false,
+  },
+  {
+    id: "iot-high-temperature",
+    category: "Environment",
+    severity: "Critical",
+    metricName: "iot_temperature_celsius",
+    metricAlias: "temperature_celsius",
+    // Max: a single hot reading must win over cooler ones in the minute.
+    aggregation: MetricsAggregationType.Max,
+    offlineFilterType: FilterType.GreaterThan,
+    onlineFilterType: FilterType.LessThanOrEqualTo,
+    threshold: 70,
+    treatNoDataAsZero: false,
+  },
+  {
+    id: "iot-high-cpu",
+    category: "System",
+    severity: "Warning",
+    metricName: "iot_cpu_usage_ratio",
+    metricAlias: "cpu_usage",
+    aggregation: MetricsAggregationType.Avg,
+    offlineFilterType: FilterType.GreaterThan,
+    onlineFilterType: FilterType.LessThanOrEqualTo,
+    // iot_cpu_usage_ratio is a 0-1 ratio, so 0.9 == 90%.
+    threshold: 0.9,
+    treatNoDataAsZero: false,
+  },
+];
+
+function buildArgs(): IoTAlertTemplateArgs {
+  return {
+    fleetIdentifier: "field-fleet-a",
+    onlineMonitorStatusId: ObjectID.generate(),
+    offlineMonitorStatusId: ObjectID.generate(),
+    defaultIncidentSeverityId: ObjectID.generate(),
+    defaultAlertSeverityId: ObjectID.generate(),
+    monitorName: "Test IoT Monitor",
+  };
+}
+
+function getIoTMonitor(step: MonitorStep): MonitorStepIoTMonitor {
+  const iotMonitor: MonitorStepIoTMonitor | undefined = step.data?.iotMonitor;
+  if (!iotMonitor) {
+    throw new Error("iotMonitor missing from monitor step");
+  }
+  return iotMonitor;
+}
+
+describe("IotAlertTemplates", () => {
+  test("every documented template id is registered and the suite is exhaustive", () => {
+    const ids: Array<string> = getAllIoTAlertTemplates().map(
+      (t: IoTAlertTemplate) => {
+        return t.id;
+      },
+    );
+    for (const tc of IOT_TEMPLATES) {
+      expect(ids).toContain(tc.id);
+    }
+    expect(ids.sort()).toEqual(
+      IOT_TEMPLATES.map((t: IoTTemplateCase) => {
+        return t.id;
+      }).sort(),
+    );
+  });
+
+  test("every template id is unique", () => {
+    const ids: Array<string> = getAllIoTAlertTemplates().map(
+      (t: IoTAlertTemplate) => {
+        return t.id;
+      },
+    );
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  test("getIoTAlertTemplateById returns undefined for an unknown id", () => {
+    expect(getIoTAlertTemplateById("nope")).toBeUndefined();
+  });
+
+  test("getIoTAlertTemplatesByCategory returns only that category and covers the catalog", () => {
+    const all: Array<IoTAlertTemplate> = getAllIoTAlertTemplates();
+    const categories: Array<IoTAlertTemplateCategory> = [
+      "Availability",
+      "Power",
+      "Connectivity",
+      "Environment",
+      "System",
+    ];
+
+    let total: number = 0;
+    for (const category of categories) {
+      const inCategory: Array<IoTAlertTemplate> =
+        getIoTAlertTemplatesByCategory(category);
+      for (const template of inCategory) {
+        expect(template.category).toBe(category);
+      }
+      total += inCategory.length;
+    }
+    expect(total).toBe(all.length);
+  });
+
+  test.each(IOT_TEMPLATES)(
+    "$id is a $severity $category template with populated copy",
+    (tc: IoTTemplateCase) => {
+      const template: IoTAlertTemplate | undefined = getIoTAlertTemplateById(
+        tc.id,
+      );
+      expect(template).toBeDefined();
+      expect(template!.category).toBe(tc.category);
+      expect(template!.severity).toBe(tc.severity);
+      expect(template!.name.length).toBeGreaterThan(0);
+      expect(template!.description.length).toBeGreaterThan(0);
+    },
+  );
+
+  test.each(IOT_TEMPLATES)(
+    "$id queries $metricName grouped per device with the intended aggregation",
+    (tc: IoTTemplateCase) => {
+      const template: IoTAlertTemplate = getIoTAlertTemplateById(tc.id)!;
+      const step: MonitorStep = template.getMonitorStep(buildArgs());
+      const monitor: MonitorStepIoTMonitor = getIoTMonitor(step);
+
+      expect(monitor.fleetIdentifier).toBe("field-fleet-a");
+
+      const queryConfigs: Array<any> = monitor.metricViewConfig
+        .queryConfigs as Array<any>;
+      expect(queryConfigs).toHaveLength(1);
+      expect(monitor.metricViewConfig.formulaConfigs).toHaveLength(0);
+
+      const queryData: any = queryConfigs[0].metricQueryData;
+      expect(queryData.filterData.metricName).toBe(tc.metricName);
+      expect(queryData.filterData.aggegationType).toBe(tc.aggregation);
+
+      /*
+       * Decision (2): one incident per device — group by the raw datapoint
+       * label, which is NOT resource-prefixed.
+       */
+      expect(queryData.groupByAttributeKeys).toEqual(["device.id"]);
+      expect(queryData.groupByAttributeKeys[0].startsWith("resource.")).toBe(
+        false,
+      );
+    },
+  );
+
+  test.each(IOT_TEMPLATES)(
+    "$id unhealthy/healthy criteria partition the range at $threshold",
+    (tc: IoTTemplateCase) => {
+      const template: IoTAlertTemplate = getIoTAlertTemplateById(tc.id)!;
+      const step: MonitorStep = template.getMonitorStep(buildArgs());
+
+      const instances: Array<any> = step.data?.monitorCriteria.data
+        ?.monitorCriteriaInstanceArray as Array<any>;
+      expect(instances).toHaveLength(2);
+      const [offline, online] = instances;
+
+      const offlineFilter: any = offline.data.filters[0];
+      const onlineFilter: any = online.data.filters[0];
+
+      expect(offlineFilter.metricMonitorOptions.metricAlias).toBe(
+        tc.metricAlias,
+      );
+      expect(onlineFilter.metricMonitorOptions.metricAlias).toBe(
+        tc.metricAlias,
+      );
+      expect(offlineFilter.value).toBe(tc.threshold);
+      expect(onlineFilter.value).toBe(tc.threshold);
+
+      /*
+       * Decision (1): pin the exact comparison direction per template — the
+       * low-value alerts invert relative to the ceiling alerts.
+       */
+      expect(offlineFilter.filterType).toBe(tc.offlineFilterType);
+      expect(onlineFilter.filterType).toBe(tc.onlineFilterType);
+
+      expect(offline.data.createIncidents).toBe(true);
+      expect(offline.data.createAlerts).toBe(true);
+      expect(online.data.createIncidents).toBe(false);
+      expect(online.data.createAlerts).toBe(false);
+    },
+  );
+
+  test.each(IOT_TEMPLATES)(
+    "$id applies TreatAsZero only when it is the Device Offline template",
+    (tc: IoTTemplateCase) => {
+      const template: IoTAlertTemplate = getIoTAlertTemplateById(tc.id)!;
+      const step: MonitorStep = template.getMonitorStep(buildArgs());
+
+      const offline: any = (
+        step.data?.monitorCriteria.data
+          ?.monitorCriteriaInstanceArray as Array<any>
+      )[0];
+      const online: any = (
+        step.data?.monitorCriteria.data
+          ?.monitorCriteriaInstanceArray as Array<any>
+      )[1];
+
+      const offlineNoDataPolicy: NoDataPolicy | undefined =
+        offline.data.filters[0].metricMonitorOptions.onNoDataPolicy;
+
+      if (tc.treatNoDataAsZero) {
+        // Decision (3): a silent registered device must fold to 0 and alert.
+        expect(offlineNoDataPolicy).toBe(NoDataPolicy.TreatAsZero);
+      } else {
+        // Everything else leaves no-data untouched to avoid false alarms.
+        expect(offlineNoDataPolicy).toBeUndefined();
+      }
+
+      // The healthy criterion never overrides the no-data policy.
+      expect(
+        online.data.filters[0].metricMonitorOptions.onNoDataPolicy,
+      ).toBeUndefined();
+    },
+  );
+
+  test("exactly one template opts into TreatAsZero", () => {
+    /*
+     * Guards decision (3) at the catalog level: if a second template ever
+     * enables TreatAsZero, this fails and forces a deliberate review.
+     */
+    const withTreatAsZero: Array<IoTTemplateCase> = IOT_TEMPLATES.filter(
+      (tc: IoTTemplateCase) => {
+        return tc.treatNoDataAsZero;
+      },
+    );
+    expect(withTreatAsZero).toHaveLength(1);
+    expect(withTreatAsZero[0]!.id).toBe("iot-device-offline");
+  });
+});

package/Tests/Types/Monitor/PodmanAlertTemplates.test.ts

@@ -0,0 +1,271 @@
+import {
+  PodmanAlertTemplate,
+  PodmanAlertTemplateArgs,
+  PodmanAlertTemplateCategory,
+  getAllPodmanAlertTemplates,
+  getPodmanAlertTemplateById,
+  getPodmanAlertTemplatesByCategory,
+} from "../../../Types/Monitor/PodmanAlertTemplates";
+import MonitorStep from "../../../Types/Monitor/MonitorStep";
+import MonitorStepPodmanMonitor from "../../../Types/Monitor/MonitorStepPodmanMonitor";
+import MetricsAggregationType from "../../../Types/Metrics/MetricsAggregationType";
+import RollingTime from "../../../Types/RollingTime/RollingTime";
+import { FilterType } from "../../../Types/Monitor/CriteriaFilter";
+import ObjectID from "../../../Types/ObjectID";
+
+/*
+ * Podman containers emit the same OTel container.* metrics as Docker, so the
+ * Podman templates mirror the Docker set. These tests lock in the same three
+ * regression-prone decisions (metric name, per-minute aggregation, and the
+ * unhealthy/healthy range partition) independently, so a divergence between
+ * the two catalogs — a renamed metric or a flipped comparison copied from one
+ * into the other — is caught here rather than in production.
+ */
+
+interface PodmanTemplateCase {
+  id: string;
+  category: PodmanAlertTemplateCategory;
+  severity: "Critical" | "Warning";
+  metricName: string;
+  metricAlias: string;
+  aggregation: MetricsAggregationType;
+  rollingTime: RollingTime;
+  offlineFilterType: FilterType;
+  onlineFilterType: FilterType;
+  threshold: number;
+}
+
+const PODMAN_TEMPLATES: Array<PodmanTemplateCase> = [
+  {
+    id: "podman-high-cpu",
+    category: "Resource",
+    severity: "Warning",
+    metricName: "container.cpu.utilization",
+    metricAlias: "container_cpu",
+    aggregation: MetricsAggregationType.Max,
+    rollingTime: RollingTime.Past5Minutes,
+    offlineFilterType: FilterType.GreaterThan,
+    onlineFilterType: FilterType.LessThanOrEqualTo,
+    threshold: 80,
+  },
+  {
+    id: "podman-high-memory",
+    category: "Resource",
+    severity: "Warning",
+    metricName: "container.memory.percent",
+    metricAlias: "container_memory",
+    aggregation: MetricsAggregationType.Max,
+    rollingTime: RollingTime.Past5Minutes,
+    offlineFilterType: FilterType.GreaterThan,
+    onlineFilterType: FilterType.LessThanOrEqualTo,
+    threshold: 85,
+  },
+  {
+    id: "podman-restart-loop",
+    category: "Container",
+    severity: "Critical",
+    metricName: "container.restarts",
+    metricAlias: "container_restarts",
+    aggregation: MetricsAggregationType.Max,
+    rollingTime: RollingTime.Past5Minutes,
+    offlineFilterType: FilterType.GreaterThan,
+    onlineFilterType: FilterType.LessThanOrEqualTo,
+    threshold: 5,
+  },
+  {
+    id: "podman-cpu-throttling",
+    category: "Resource",
+    severity: "Warning",
+    metricName: "container.cpu.throttling_data.throttled_time",
+    metricAlias: "cpu_throttled",
+    aggregation: MetricsAggregationType.Max,
+    rollingTime: RollingTime.Past5Minutes,
+    // throttled_time is non-negative: (> 0) unhealthy, (= 0) healthy partitions it.
+    offlineFilterType: FilterType.GreaterThan,
+    onlineFilterType: FilterType.EqualTo,
+    threshold: 0,
+  },
+  {
+    id: "podman-high-pids",
+    category: "Container",
+    severity: "Warning",
+    metricName: "container.pids.count",
+    metricAlias: "pids_count",
+    aggregation: MetricsAggregationType.Max,
+    rollingTime: RollingTime.Past5Minutes,
+    offlineFilterType: FilterType.GreaterThan,
+    onlineFilterType: FilterType.LessThanOrEqualTo,
+    threshold: 500,
+  },
+  {
+    id: "podman-container-down",
+    category: "Container",
+    severity: "Critical",
+    metricName: "container.uptime",
+    metricAlias: "container_uptime",
+    aggregation: MetricsAggregationType.Min,
+    rollingTime: RollingTime.Past1Minute,
+    // uptime is non-negative: (= 0) unhealthy, (> 0) healthy partitions it.
+    offlineFilterType: FilterType.EqualTo,
+    onlineFilterType: FilterType.GreaterThan,
+    threshold: 0,
+  },
+];
+
+function buildArgs(): PodmanAlertTemplateArgs {
+  return {
+    hostIdentifier: "podman-host-01",
+    onlineMonitorStatusId: ObjectID.generate(),
+    offlineMonitorStatusId: ObjectID.generate(),
+    defaultIncidentSeverityId: ObjectID.generate(),
+    defaultAlertSeverityId: ObjectID.generate(),
+    monitorName: "Test Podman Monitor",
+  };
+}
+
+function getPodmanMonitor(step: MonitorStep): MonitorStepPodmanMonitor {
+  const podmanMonitor: MonitorStepPodmanMonitor | undefined =
+    step.data?.podmanMonitor;
+  if (!podmanMonitor) {
+    throw new Error("podmanMonitor missing from monitor step");
+  }
+  return podmanMonitor;
+}
+
+describe("PodmanAlertTemplates", () => {
+  test("every documented template id is registered and the suite is exhaustive", () => {
+    const ids: Array<string> = getAllPodmanAlertTemplates().map(
+      (t: PodmanAlertTemplate) => {
+        return t.id;
+      },
+    );
+    for (const tc of PODMAN_TEMPLATES) {
+      expect(ids).toContain(tc.id);
+    }
+    expect(ids.sort()).toEqual(
+      PODMAN_TEMPLATES.map((t: PodmanTemplateCase) => {
+        return t.id;
+      }).sort(),
+    );
+  });
+
+  test("every template id is unique", () => {
+    const ids: Array<string> = getAllPodmanAlertTemplates().map(
+      (t: PodmanAlertTemplate) => {
+        return t.id;
+      },
+    );
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  test("getPodmanAlertTemplateById returns undefined for an unknown id", () => {
+    expect(getPodmanAlertTemplateById("does-not-exist")).toBeUndefined();
+  });
+
+  test("getPodmanAlertTemplatesByCategory partitions the catalog by category", () => {
+    const all: Array<PodmanAlertTemplate> = getAllPodmanAlertTemplates();
+    const categories: Array<PodmanAlertTemplateCategory> = [
+      "Container",
+      "Resource",
+      "Host",
+    ];
+
+    let total: number = 0;
+    for (const category of categories) {
+      const inCategory: Array<PodmanAlertTemplate> =
+        getPodmanAlertTemplatesByCategory(category);
+      for (const template of inCategory) {
+        expect(template.category).toBe(category);
+      }
+      total += inCategory.length;
+    }
+    expect(total).toBe(all.length);
+  });
+
+  test.each(PODMAN_TEMPLATES)(
+    "$id is a $severity $category template with populated copy",
+    (tc: PodmanTemplateCase) => {
+      const template: PodmanAlertTemplate | undefined =
+        getPodmanAlertTemplateById(tc.id);
+      expect(template).toBeDefined();
+      expect(template!.category).toBe(tc.category);
+      expect(template!.severity).toBe(tc.severity);
+      expect(template!.name.length).toBeGreaterThan(0);
+      expect(template!.description.length).toBeGreaterThan(0);
+    },
+  );
+
+  test.each(PODMAN_TEMPLATES)(
+    "$id queries $metricName with the intended aggregation and window",
+    (tc: PodmanTemplateCase) => {
+      const template: PodmanAlertTemplate = getPodmanAlertTemplateById(tc.id)!;
+      const step: MonitorStep = template.getMonitorStep(buildArgs());
+      const monitor: MonitorStepPodmanMonitor = getPodmanMonitor(step);
+
+      expect(monitor.hostIdentifier).toBe("podman-host-01");
+
+      const queryConfigs: Array<any> = monitor.metricViewConfig
+        .queryConfigs as Array<any>;
+      expect(queryConfigs).toHaveLength(1);
+      expect(monitor.metricViewConfig.formulaConfigs).toHaveLength(0);
+
+      const filterData: any = queryConfigs[0].metricQueryData.filterData;
+      expect(filterData.metricName).toBe(tc.metricName);
+      expect(filterData.aggegationType).toBe(tc.aggregation);
+      expect(monitor.rollingTime).toBe(tc.rollingTime);
+    },
+  );
+
+  test.each(PODMAN_TEMPLATES)(
+    "$id unhealthy/healthy criteria partition the range at $threshold",
+    (tc: PodmanTemplateCase) => {
+      const template: PodmanAlertTemplate = getPodmanAlertTemplateById(tc.id)!;
+      const step: MonitorStep = template.getMonitorStep(buildArgs());
+
+      const instances: Array<any> = step.data?.monitorCriteria.data
+        ?.monitorCriteriaInstanceArray as Array<any>;
+      expect(instances).toHaveLength(2);
+      const [offline, online] = instances;
+
+      const offlineFilter: any = offline.data.filters[0];
+      const onlineFilter: any = online.data.filters[0];
+
+      expect(offlineFilter.metricMonitorOptions.metricAlias).toBe(
+        tc.metricAlias,
+      );
+      expect(onlineFilter.metricMonitorOptions.metricAlias).toBe(
+        tc.metricAlias,
+      );
+      expect(offlineFilter.value).toBe(tc.threshold);
+      expect(onlineFilter.value).toBe(tc.threshold);
+
+      expect(offlineFilter.filterType).toBe(tc.offlineFilterType);
+      expect(onlineFilter.filterType).toBe(tc.onlineFilterType);
+
+      expect(offline.data.createIncidents).toBe(true);
+      expect(offline.data.createAlerts).toBe(true);
+      expect(offline.data.incidents).toHaveLength(1);
+      expect(offline.data.alerts).toHaveLength(1);
+      expect(offline.data.monitorStatusId).toBeDefined();
+
+      expect(online.data.createIncidents).toBe(false);
+      expect(online.data.createAlerts).toBe(false);
+      expect(online.data.incidents).toHaveLength(0);
+      expect(online.data.alerts).toHaveLength(0);
+    },
+  );
+
+  test("incidents auto-resolve so a recovered container clears itself", () => {
+    for (const tc of PODMAN_TEMPLATES) {
+      const step: MonitorStep = getPodmanAlertTemplateById(
+        tc.id,
+      )!.getMonitorStep(buildArgs());
+      const offline: any = (
+        step.data?.monitorCriteria.data
+          ?.monitorCriteriaInstanceArray as Array<any>
+      )[0];
+      expect(offline.data.incidents[0].autoResolveIncident).toBe(true);
+      expect(offline.data.alerts[0].autoResolveAlert).toBe(true);
+    }
+  });
+});