@oneuptime/common 12.0.33 → 13.0.0

package/Types/Monitor/IotAlertTemplates.ts

@@ -2,16 +2,15 @@ import ObjectID from "../ObjectID";
 import MonitorStep from "./MonitorStep";
 import MonitorCriteria from "./MonitorCriteria";
 import MonitorCriteriaInstance from "./MonitorCriteriaInstance";
-import FilterCondition from "../Filter/FilterCondition";
 import {
-  CheckOn,
-  FilterType,
-  EvaluateOverTimeType,
-  NoDataPolicy,
-} from "./CriteriaFilter";
+  buildHealthyCriteriaInstance,
+  buildUnhealthyCriteriaInstance,
+} from "./Recommendation/RecommendationCriteriaBuilder";
+import { FilterType, EvaluateOverTimeType } from "./CriteriaFilter";
 import MonitorStepIoTMonitor from "./MonitorStepIoTMonitor";
 import RollingTime from "../RollingTime/RollingTime";
 import MetricsAggregationType from "../Metrics/MetricsAggregationType";
+import { getIoTMetricByMetricName } from "./IotMetricCatalog";
 
 export type IoTAlertTemplateCategory =
   | "Availability"
@@ -107,72 +106,17 @@ export function buildIoTOfflineCriteriaInstance(args: {
   incidentDescription?: string;
   criteriaName?: string;
   criteriaDescription?: string;
+  metricAggregationType?: EvaluateOverTimeType | undefined;
   /*
-   * Evaluate an empty (no data) series as 0 instead of skipping it.
-   * This is what lets REGISTERED devices that go completely silent
-   * trip the criteria: monitor evaluation injects an empty synthetic
-   * series per registered-but-silent device, TreatAsZero folds it to
-   * 0, and e.g. Min(iot_device_up) < 1 fires. Only the Device Offline
-   * template opts in — treating no-data as zero on a battery or
-   * temperature threshold would false-alarm for silent devices.
+   * A device that has stopped reporting emits no series at all, so the
+   * offline comparison has to count absence as zero rather than skip.
    */
-  treatNoDataAsZero?: boolean;
+  treatNoDataAsZero?: boolean | undefined;
 }): MonitorCriteriaInstance {
-  const instance: MonitorCriteriaInstance = new MonitorCriteriaInstance();
-
-  const incidentTitle: string =
-    args.incidentTitle || `${args.monitorName} - Alert Triggered`;
-  const incidentDescription: string =
-    args.incidentDescription ||
-    `${args.monitorName} has triggered an alert condition. See root cause for detailed IoT device information.`;
-
-  instance.data = {
-    id: ObjectID.generate().toString(),
-    monitorStatusId: args.offlineMonitorStatusId,
-    filterCondition: FilterCondition.Any,
-    filters: [
-      {
-        checkOn: CheckOn.MetricValue,
-        filterType: args.filterType,
-        metricMonitorOptions: {
-          metricAggregationType: EvaluateOverTimeType.AnyValue,
-          metricAlias: args.metricAlias,
-          ...(args.treatNoDataAsZero
-            ? { onNoDataPolicy: NoDataPolicy.TreatAsZero }
-            : {}),
-        },
-        value: args.value,
-      },
-    ],
-    incidents: [
-      {
-        title: incidentTitle,
-        description: incidentDescription,
-        incidentSeverityId: args.incidentSeverityId,
-        autoResolveIncident: true,
-        id: ObjectID.generate().toString(),
-        onCallPolicyIds: [],
-      },
-    ],
-    alerts: [
-      {
-        title: incidentTitle,
-        description: incidentDescription,
-        alertSeverityId: args.alertSeverityId,
-        autoResolveAlert: true,
-        id: ObjectID.generate().toString(),
-        onCallPolicyIds: [],
-      },
-    ],
-    changeMonitorStatus: true,
-    createIncidents: true,
-    createAlerts: true,
-    name: args.criteriaName || `${args.monitorName} - Unhealthy`,
-    description:
-      args.criteriaDescription || `Criteria for detecting unhealthy state.`,
-  };
-
-  return instance;
+  return buildUnhealthyCriteriaInstance({
+    ...args,
+    resourceNoun: "device",
+  });
 }
 
 export function buildIoTOnlineCriteriaInstance(args: {
@@ -180,34 +124,12 @@ export function buildIoTOnlineCriteriaInstance(args: {
   metricAlias: string;
   filterType: FilterType;
   value: number;
+  recoveryValue?: number | undefined;
+  marginFraction?: number | undefined;
+  isBinaryMetric?: boolean | undefined;
+  metricAggregationType?: EvaluateOverTimeType | undefined;
 }): MonitorCriteriaInstance {
-  const instance: MonitorCriteriaInstance = new MonitorCriteriaInstance();
-
-  instance.data = {
-    id: ObjectID.generate().toString(),
-    monitorStatusId: args.onlineMonitorStatusId,
-    filterCondition: FilterCondition.Any,
-    filters: [
-      {
-        checkOn: CheckOn.MetricValue,
-        filterType: args.filterType,
-        metricMonitorOptions: {
-          metricAggregationType: EvaluateOverTimeType.AnyValue,
-          metricAlias: args.metricAlias,
-        },
-        value: args.value,
-      },
-    ],
-    incidents: [],
-    alerts: [],
-    changeMonitorStatus: true,
-    createIncidents: false,
-    createAlerts: false,
-    name: "Healthy",
-    description: "Criteria for healthy state.",
-  };
-
-  return instance;
+  return buildHealthyCriteriaInstance(args);
 }
 
 export function buildIoTMonitorConfig(args: {
@@ -218,7 +140,27 @@ export function buildIoTMonitorConfig(args: {
   aggregationType: MetricsAggregationType;
   attributes?: Record<string, string>;
   groupByAttributeKey?: string | undefined;
+  /*
+   * Display unit for the series. Defaults to the unit IotMetricCatalog
+   * already declares for `metricName`, which every template was throwing
+   * away: MetricMonitorCriteria uses this as the sample unit AND (absent an
+   * explicit thresholdUnit) as the threshold unit, so without it a root
+   * cause reads "is -103.2 which is less than -100" instead of "is -103.2
+   * dBm which is less than -100 dBm". The IoT device-detail charts already
+   * label these same metrics "%", "dBm" and "°C".
+   *
+   * Safe against silent rescaling: setting a display unit enables
+   * MetricResultUnitConverter, but "dBm", "°C" and "ratio" belong to no
+   * MetricUnitUtil family and are passed through untouched. The only
+   * convertible catalog units are "%", "bytes" and "s", and there the
+   * conversion is the correction — a device declaring the dimensionless "1"
+   * and sending a 0-1 battery fraction currently satisfies "< 20" forever.
+   */
+  legendUnit?: string | undefined;
 }): MonitorStepIoTMonitor {
+  const legendUnit: string | undefined =
+    args.legendUnit ?? getIoTMetricByMetricName(args.metricName)?.unit;
+
   return {
     fleetIdentifier: args.fleetIdentifier,
     resourceFilters: {},
@@ -230,7 +172,7 @@ export function buildIoTMonitorConfig(args: {
             title: args.metricAlias,
             description: args.metricAlias,
             legend: args.metricAlias,
-            legendUnit: undefined,
+            legendUnit: legendUnit,
           },
           metricQueryData: {
             filterData: {
@@ -356,10 +298,38 @@ const deviceOfflineTemplate: IoTAlertTemplate = {
         fleetIdentifier: args.fleetIdentifier,
         metricName: "iot_device_up",
         metricAlias,
-        rollingTime: RollingTime.Past5Minutes,
         /*
-         * Min per device — a single down push trips the threshold instead
-         * of being masked by pushes where the device was still up.
+         * This window is the SILENCE GRACE PERIOD, not the detection
+         * latency.
+         *
+         * A registered device that emits nothing gets a synthetic empty
+         * series (IoTDeviceAbsenceSeries, seeded by
+         * MonitorTelemetryMonitor.injectExpectedAbsentIoTDeviceSeries from
+         * the enabled IoTDeviceCredential rows, with no recency aging), and
+         * TreatAsZero folds that to 0 and trips `< 1`. Crucially the empty
+         * case reaches the comparator as a SCALAR — MetricMonitorCriteria
+         * passes `0`, not `[0]`, and CompareCriteria short-circuits a scalar
+         * before any quantifier — so sustained evaluation gives absence no
+         * protection and the window length is the only knob there is.
+         *
+         * At five minutes, every device whose push interval exceeded the
+         * window was declared Offline in every window it skipped and
+         * resolved in the window it pushed. Thirty minutes is twice the
+         * fifteen the inventory already allows a device to be silent
+         * (IoTDeviceService.getStaleThresholdMinutes), which covers duty
+         * cycles up to roughly a quarter hour. A device that reports less
+         * often than that still needs a hand-widened window or a disabled
+         * credential — a fleet-wide template cannot know its interval.
+         *
+         * The cost is that silent-death alerting now lags the inventory's
+         * Down flip by about fifteen minutes. Detection of a device that
+         * explicitly reports down is unaffected — see the AnyValue note on
+         * the firing filter below.
+         */
+        rollingTime: RollingTime.Past30Minutes,
+        /*
+         * Min per device — a single down push in a minute wins over pushes
+         * where the device was still up.
          */
         aggregationType: MetricsAggregationType.Min,
         attributes: {},
@@ -373,11 +343,30 @@ const deviceOfflineTemplate: IoTAlertTemplate = {
         metricAlias,
         filterType: FilterType.LessThan,
         value: 1,
+        /*
+         * The documented exception to SustainedEvaluation, because this
+         * signal is an EVENT and not a level: `iot_device_up = 0` is the
+         * device — or its broker's MQTT Last Will — explicitly declaring
+         * itself down. A binary heartbeat has no scrape-to-scrape jitter to
+         * smooth away, and requiring AllValues over a thirty-minute window
+         * would delay the Last Will path (documented as detection with "no
+         * polling, no missed-scrape delay") by that whole window.
+         *
+         * Still mutually exclusive with the healthy criteria, but only
+         * because that side opts OUT of the recovery dead band
+         * (`isBinaryMetric: true` below — the metric is boolean). With the
+         * opt-out, "some value < 1" over a non-empty window is the exact
+         * negation of "all values >= 1"; without it the healthy side
+         * recovers at 1.1 and this claim is false, so the two must move
+         * together. On the absence path only this side carries a no-data
+         * policy, so only this side can match.
+         */
+        metricAggregationType: EvaluateOverTimeType.AnyValue,
         incidentTitle: `[IoT] Device Offline - ${args.monitorName}`,
         incidentDescription: `An IoT device is reporting as down (iot_device_up = 0) or has stopped reporting entirely. The device is unreachable, powered off, or has lost connectivity to its gateway. Check the root cause for the affected device id, verify the device's power and network state, and confirm its gateway is forwarding telemetry.`,
         criteriaName: "Device Offline - iot_device_up < 1",
         criteriaDescription:
-          "Triggers when any device reports iot_device_up below 1 over the monitoring window, or when a registered device goes silent.",
+          "Triggers when any device reports iot_device_up below 1, or when a registered device stays silent for the whole 30-minute window.",
         treatNoDataAsZero: true,
       }),
       onlineCriteriaInstance: buildIoTOnlineCriteriaInstance({
@@ -385,6 +374,12 @@ const deviceOfflineTemplate: IoTAlertTemplate = {
         metricAlias,
         filterType: FilterType.GreaterThanOrEqualTo,
         value: 1,
+        /*
+         * `iot_device_up` is strictly 0 or 1, so the shared 10% recovery dead band
+         * would put this at `>= 1.1` — unreachable, leaving the monitor
+         * permanently unable to report healthy.
+         */
+        isBinaryMetric: true,
       }),
     });
   },
@@ -505,8 +500,15 @@ const highTemperatureTemplate: IoTAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past5Minutes,
         /*
-         * Max per device — a single hot reading should trip the threshold
-         * instead of being masked by cooler readings in the same minute.
+         * Max per device, deliberately overriding the catalog's declared
+         * Avg default (IotMetricCatalog: iot-temperature) — a hot reading
+         * must not be masked by cooler readings in the SAME MINUTE.
+         *
+         * This is a per-minute reducer only. The criteria then quantifies
+         * across the minutes with the sustained default, so the condition is
+         * "the peak reading in every minute of the window exceeded 70°C",
+         * not "one sample anywhere spiked". A single hot reading does not
+         * page.
          */
         aggregationType: MetricsAggregationType.Max,
         attributes: {},
@@ -568,8 +570,14 @@ const highCpuTemplate: IoTAlertTemplate = {
         monitorName: args.monitorName,
         metricAlias,
         filterType: FilterType.GreaterThan,
+        /*
+         * A raw 0-1 ratio, not a percentage — IoTSnapshotScan scales it to
+         * percent only for the device inventory column, never for the stored
+         * metric. 0.9 IS 90%, but the criteria compares 0.9 and the root
+         * cause prints "0.94 ratio", so the title says ratio too.
+         */
         value: 0.9,
-        incidentTitle: `[IoT] High CPU Usage (>90%) - ${args.monitorName}`,
+        incidentTitle: `[IoT] High CPU Usage (ratio >0.9) - ${args.monitorName}`,
         incidentDescription: `An IoT device's CPU usage has exceeded 90% of its capacity. Sustained high CPU can delay telemetry, drain the battery faster, and cause the device to become unresponsive. Check the root cause for the affected device id, then investigate the workload running on the device.`,
         criteriaName: "High CPU - iot_cpu_usage_ratio > 0.9",
         criteriaDescription: