@oneuptime/common 12.0.14 → 12.0.16

package/Server/Utils/Measurement/MeasurementMetricWriter.ts

@@ -0,0 +1,189 @@
+import MetricType from "../../../Models/DatabaseModels/MetricType";
+import MutableMetric from "../../../Models/AnalyticsModels/MutableMetric";
+import { MetricPointType } from "../../../Models/AnalyticsModels/Metric";
+import GlobalConfigService from "../../Services/GlobalConfigService";
+import MutableMetricService from "../../Services/MutableMetricService";
+import GlobalConfig from "../../../Models/DatabaseModels/GlobalConfig";
+import ObjectID from "../../../Types/ObjectID";
+import OneUptimeDate from "../../../Types/Date";
+import ServiceType from "../../../Types/Telemetry/ServiceType";
+import TelemetryUtil from "../Telemetry/Telemetry";
+import { JSONObject } from "../../../Types/JSON";
+import logger from "../Logger";
+
+export interface MeasurementMetricPoint {
+  metricName: string;
+  measurementId: string;
+  measurementKey: string;
+  measurementName: string;
+  description?: string | undefined;
+  unit?: string | undefined;
+  valueInSeconds: number;
+  time: Date;
+}
+
+const DEFAULT_METRIC_RETENTION_IN_DAYS: number = 180;
+
+/*
+ * Writes measurement values into the existing mutable-metric pipeline.
+ *
+ * The one thing this must get right is the tombstone scope.
+ * MutableMetricService.replaceEntityMetrics tombstones every live metric
+ * point whose name is in `metricNames` and which is not in the desired set it
+ * was handed. So the measurement writer owns its OWN name list -- the
+ * project's measurement metric names, and nothing else -- and never appends
+ * those names to the built-in refresh's replace list. Doing the latter would
+ * make every state change tombstone every measurement point, silently, since
+ * the built-in refresh has no measurement points in its desired set.
+ */
+export default class MeasurementMetricWriter {
+  public static async write(data: {
+    projectId: ObjectID;
+    primaryEntityId: ObjectID;
+    primaryEntityType: ServiceType;
+    // Every measurement metric name in the project, enabled or not.
+    allMeasurementMetricNames: Array<string>;
+    // Only the points that actually have a value; disabled ones are omitted.
+    points: Array<MeasurementMetricPoint>;
+    baseAttributes: JSONObject;
+  }): Promise<void> {
+    if (data.allMeasurementMetricNames.length === 0) {
+      return;
+    }
+
+    const retentionDate: Date = OneUptimeDate.addRemoveDays(
+      OneUptimeDate.getCurrentDate(),
+      await MeasurementMetricWriter.getMetricRetentionInDays(),
+    );
+
+    const metrics: Array<MutableMetric> = [];
+    const metricTypesMap: Record<string, MetricType> = {};
+
+    for (const point of data.points) {
+      const metric: MutableMetric = new MutableMetric();
+
+      metric.projectId = data.projectId;
+      metric.primaryEntityId = data.primaryEntityId;
+      metric.primaryEntityType = data.primaryEntityType;
+      metric.name = point.metricName;
+
+      /*
+       * Per-definition point identity, mirroring the built-in
+       * `time-in-state:<timelineRowId>` shape. Sharing one identity across
+       * definitions would make each refresh overwrite the others.
+       */
+      metric.metricPointId = `measurement:${point.measurementId}`;
+      metric.value = point.valueInSeconds;
+      metric.time = point.time;
+      metric.timeUnixNano = OneUptimeDate.toUnixNano(point.time);
+      metric.metricPointType = MetricPointType.Sum;
+      metric.retentionDate = retentionDate;
+
+      metric.attributes = {
+        ...data.baseAttributes,
+        /*
+         * Namespaced, following the oneuptime.label.* / oneuptime.customField.*
+         * convention, so they cannot collide with the unprefixed camelCase
+         * dimensions the built-in metrics carry.
+         */
+        "oneuptime.measurement.id": point.measurementId,
+        "oneuptime.measurement.key": point.measurementKey,
+        "oneuptime.measurement.name": point.measurementName,
+      };
+      metric.attributeKeys = TelemetryUtil.getAttributeKeys(metric.attributes);
+
+      metrics.push(metric);
+
+      const metricType: MetricType = new MetricType();
+      metricType.name = point.metricName;
+      metricType.description =
+        point.description ||
+        `${point.measurementName}, a measurement defined for this project`;
+      metricType.unit = point.unit || "seconds";
+      metricTypesMap[point.metricName] = metricType;
+    }
+
+    await MutableMetricService.replaceEntityMetrics({
+      projectId: data.projectId,
+      primaryEntityId: data.primaryEntityId,
+      primaryEntityType: data.primaryEntityType,
+      metricNames: data.allMeasurementMetricNames,
+      metrics: metrics,
+      retentionDate: retentionDate,
+    });
+
+    if (Object.keys(metricTypesMap).length === 0) {
+      return;
+    }
+
+    /*
+     * Registering the name is what makes a measurement appear in the
+     * dashboard chart picker -- the picker reads MetricType rows, not any
+     * enum, so no dashboard code is needed for a new measurement.
+     */
+    TelemetryUtil.indexMetricNameServiceNameMap({
+      metricNameServiceNameMap: metricTypesMap,
+      projectId: data.projectId,
+    }).catch((err: Error) => {
+      logger.error(err);
+    });
+  }
+
+  /*
+   * Tombstones every measurement point for one entity. Used when the entity
+   * is deleted, so its points leave the charts rather than lingering until
+   * the retention date.
+   */
+  public static async tombstoneAll(data: {
+    projectId: ObjectID;
+    primaryEntityId: ObjectID;
+    primaryEntityType: ServiceType;
+    allMeasurementMetricNames: Array<string>;
+  }): Promise<void> {
+    if (data.allMeasurementMetricNames.length === 0) {
+      return;
+    }
+
+    const retentionDate: Date = OneUptimeDate.addRemoveDays(
+      OneUptimeDate.getCurrentDate(),
+      await MeasurementMetricWriter.getMetricRetentionInDays(),
+    );
+
+    await MutableMetricService.tombstoneEntityMetrics({
+      projectId: data.projectId,
+      primaryEntityId: data.primaryEntityId,
+      primaryEntityType: data.primaryEntityType,
+      metricNames: data.allMeasurementMetricNames,
+      retentionDate: retentionDate,
+    });
+  }
+
+  private static async getMetricRetentionInDays(): Promise<number> {
+    try {
+      const globalConfig: GlobalConfig | null =
+        await GlobalConfigService.findOneBy({
+          query: {
+            _id: ObjectID.getZeroObjectID().toString(),
+          },
+          props: {
+            isRoot: true,
+          },
+          select: {
+            monitorMetricRetentionInDays: true,
+          },
+        });
+
+      if (
+        globalConfig &&
+        globalConfig.monitorMetricRetentionInDays !== undefined &&
+        globalConfig.monitorMetricRetentionInDays !== null
+      ) {
+        return globalConfig.monitorMetricRetentionInDays;
+      }
+    } catch (err) {
+      logger.error(err as Error);
+    }
+
+    return DEFAULT_METRIC_RETENTION_IN_DAYS;
+  }
+}

package/Server/Utils/Monitor/Criteria/APIRequestCriteria.ts

@@ -1,6 +1,6 @@
 import DataToProcess from "../DataToProcess";
 import CompareCriteria from "./CompareCriteria";
-import EvaluateOverTime from "./EvaluateOverTime";
+import EvaluateOverTime, { OverTimeCriteriaValue } from "./EvaluateOverTime";
 import { JSONObject } from "../../../../Types/JSON";
 import {
   CheckOn,
@@ -10,50 +10,65 @@ import {
 import ProbeMonitorResponse from "../../../../Types/Probe/ProbeMonitorResponse";
 import Typeof from "../../../../Types/Typeof";
 import CaptureSpan from "../../Telemetry/CaptureSpan";
-import logger from "../../Logger";
 
 export default class APIRequestCriteria {
   @CaptureSpan()
   public static async isMonitorInstanceCriteriaFilterMet(input: {
     dataToProcess: DataToProcess;
     criteriaFilter: CriteriaFilter;
+    /*
+     * The monitor's monitoringInterval cron. Over-time filters use it to
+     * work out how many samples a fully covered window should hold, so a
+     * monitor that has only just started is not mistaken for one whose
+     * whole window is breaching.
+     */
+    monitoringInterval?: string | undefined;
   }): Promise<string | null> {
     // Server Monitoring Checks
 
     let threshold: number | string | undefined | null =
       input.criteriaFilter.value;
 
-    let overTimeValue: Array<number | boolean> | number | boolean | undefined =
-      undefined;
+    const overTime: OverTimeCriteriaValue =
+      await EvaluateOverTime.getOverTimeValueForCriteriaFilter({
+        projectId: (input.dataToProcess as ProbeMonitorResponse).projectId,
+        monitorId: input.dataToProcess.monitorId!,
+        criteriaFilter: input.criteriaFilter,
+        /*
+         * Only the disk-usage series carries a diskPath attribute, so
+         * scoping any other series by it would filter against an attribute
+         * no row has - and an empty window now means "cannot judge yet"
+         * rather than "compare the live value", which would silence the
+         * filter outright.
+         */
+        miscData:
+          input.criteriaFilter.checkOn === CheckOn.DiskUsagePercent
+            ? (input.criteriaFilter.serverMonitorOptions as JSONObject)
+            : undefined,
+        monitoringInterval: input.monitoringInterval,
+      });
 
-    if (
-      input.criteriaFilter.evaluateOverTime &&
-      input.criteriaFilter.evaluateOverTimeOptions
-    ) {
-      try {
-        overTimeValue = await EvaluateOverTime.getValueOverTime({
-          projectId: (input.dataToProcess as ProbeMonitorResponse).projectId,
-          monitorId: input.dataToProcess.monitorId!,
-          evaluateOverTimeOptions: input.criteriaFilter.evaluateOverTimeOptions,
-          metricType: input.criteriaFilter.checkOn,
-          miscData: input.criteriaFilter.serverMonitorOptions as JSONObject,
-        });
-
-        if (Array.isArray(overTimeValue) && overTimeValue.length === 0) {
-          overTimeValue = undefined;
-        }
-      } catch (err) {
-        logger.error(
-          `Error in getting over time value for ${input.criteriaFilter.checkOn}`,
-        );
-        logger.error(err);
-        overTimeValue = undefined;
-      }
+    /*
+     * The window could not back this over-time filter (nothing recorded yet,
+     * or the monitor has not been running long enough to cover it). Return
+     * the decision the no-data policy already made instead of falling
+     * through to the value that arrived with this one check - that fallback
+     * is what let "all values over the last N minutes" fire off a single
+     * bad reading.
+     */
+    if (overTime.earlyReturn) {
+      return overTime.earlyReturn.result;
     }
 
+    const overTimeValue:
+      | Array<number | boolean>
+      | number
+      | boolean
+      | undefined = overTime.value;
+
     if (input.criteriaFilter.checkOn === CheckOn.IsOnline) {
       const currentIsOnline: boolean | Array<boolean> =
-        (overTimeValue as Array<boolean>) ||
+        (overTimeValue as Array<boolean>) ??
         (input.dataToProcess as ProbeMonitorResponse).isOnline;
 
       return CompareCriteria.compareCriteriaBoolean({
@@ -64,7 +79,7 @@ export default class APIRequestCriteria {
 
     if (input.criteriaFilter.checkOn === CheckOn.IsRequestTimeout) {
       const currentIsTimeout: boolean | Array<boolean> =
-        (overTimeValue as Array<boolean>) ||
+        (overTimeValue as Array<boolean>) ??
         (input.dataToProcess as ProbeMonitorResponse).isTimeout;
 
       return CompareCriteria.compareCriteriaBoolean({
@@ -78,7 +93,7 @@ export default class APIRequestCriteria {
       threshold = CompareCriteria.convertToNumber(threshold);
 
       const value: Array<number> | number =
-        (overTimeValue as Array<number>) ||
+        (overTimeValue as Array<number>) ??
         (input.dataToProcess as ProbeMonitorResponse).responseTimeInMs!;
 
       return CompareCriteria.compareCriteriaNumbers({
@@ -124,7 +139,7 @@ export default class APIRequestCriteria {
       ).pingResponse?.packetLossPercent;
 
       const value: Array<number> | number | undefined =
-        (overTimeValue as Array<number>) || packetLossPercent;
+        (overTimeValue as Array<number>) ?? packetLossPercent;
 
       if (value === undefined) {
         return null;
@@ -146,7 +161,7 @@ export default class APIRequestCriteria {
       ).pingResponse?.jitterInMs;
 
       const value: Array<number> | number | undefined =
-        (overTimeValue as Array<number>) || jitterInMs;
+        (overTimeValue as Array<number>) ?? jitterInMs;
 
       if (value === undefined) {
         return null;
@@ -169,7 +184,7 @@ export default class APIRequestCriteria {
       threshold = CompareCriteria.convertToNumber(threshold);
 
       const value: Array<number> | number =
-        (overTimeValue as Array<number>) ||
+        (overTimeValue as Array<number>) ??
         (input.dataToProcess as ProbeMonitorResponse).responseCode!;
 
       return CompareCriteria.compareCriteriaNumbers({

package/Server/Utils/Monitor/Criteria/CountAnomaly.ts

@@ -0,0 +1,182 @@
+import {
+  AnomalyDetectionMethod,
+  FilterType,
+} from "../../../../Types/Monitor/CriteriaFilter";
+
+/**
+ * Consistency constant that maps a Median Absolute Deviation to the
+ * standard deviation of a Gaussian (σ ≈ 1.4826 × MAD), so the same
+ * sigmaCount sensitivity levels apply to both anomaly methods.
+ */
+export const MAD_TO_SIGMA: number = 1.4826;
+
+/**
+ * Descriptive statistics of a set of per-minute telemetry counts —
+ * one hour-of-week baseline cell aggregated over a rolling window.
+ * Computed in app code (not SQL) so the math is pure and unit-testable;
+ * the input is at most `60 × ceil(windowDays / 7)` numbers.
+ */
+export interface CountBaselineStats {
+  /** Number of non-empty minute cells that contributed. */
+  sampleCount: number;
+  mean: number;
+  /** Population standard deviation. */
+  stddev: number;
+  median: number;
+  /** MAD × 1.4826 → σ-equivalent, used by the MedianMad method. */
+  madSigma: number;
+  minObserved: number;
+  maxObserved: number;
+}
+
+/**
+ * Baseline summary returned by the span/log count baseline services:
+ * the stats plus the reliability verdict and lookup coordinates.
+ * Mirrors `BaselineSummary` from MetricBaselineService.
+ */
+export interface CountBaselineSummary extends CountBaselineStats {
+  /**
+   * Whether this cell meets the minimum sample threshold to be trusted.
+   * Callers must refuse to evaluate against an unreliable baseline —
+   * the "Learning" cold-start state.
+   */
+  isReliable: boolean;
+  /** Window the baseline was computed over (days). */
+  windowDays: number;
+  hourOfWeek: number;
+}
+
+export interface CountAnomalyEvaluation {
+  breaches: boolean;
+  /** (observed - center) / spread — signed sigma distance. */
+  observedSigma: number;
+  expectedHigh: number;
+  expectedLow: number;
+  /** Baseline center actually compared against (mean or median). */
+  center: number;
+  /** Baseline spread actually compared against (stddev or MAD×1.4826). */
+  spread: number;
+}
+
+/**
+ * Pure math for count-based anomaly criteria (CheckOn.SpanCount /
+ * CheckOn.LogCount with FilterType.AnomalouslyHigh/Low/Anomalous).
+ * The services compute stats through here so the write-side MV cells
+ * and the eval-time comparison agree on what a "sample" is.
+ */
+export default class CountAnomaly {
+  /**
+   * Compute baseline stats over a cell's per-minute counts. Returns
+   * null for an empty input — the caller treats that as "no baseline"
+   * (Learning), same as a missing row.
+   */
+  public static computeStats(counts: Array<number>): CountBaselineStats | null {
+    if (counts.length === 0) {
+      return null;
+    }
+
+    let sum: number = 0;
+    let min: number = counts[0]!;
+    let max: number = counts[0]!;
+    for (const value of counts) {
+      sum += value;
+      if (value < min) {
+        min = value;
+      }
+      if (value > max) {
+        max = value;
+      }
+    }
+    const mean: number = sum / counts.length;
+
+    let sumSquaredDeviation: number = 0;
+    for (const value of counts) {
+      sumSquaredDeviation += (value - mean) * (value - mean);
+    }
+    const stddev: number = Math.sqrt(sumSquaredDeviation / counts.length);
+
+    const median: number = CountAnomaly.medianOf(counts);
+    const absoluteDeviations: Array<number> = counts.map((value: number) => {
+      return Math.abs(value - median);
+    });
+    const madSigma: number =
+      CountAnomaly.medianOf(absoluteDeviations) * MAD_TO_SIGMA;
+
+    return {
+      sampleCount: counts.length,
+      mean,
+      stddev,
+      median,
+      madSigma,
+      minObserved: min,
+      maxObserved: max,
+    };
+  }
+
+  /**
+   * Compare an observed per-minute rate to a baseline cell. Returns
+   * null when the baseline has zero spread — any deviation at all would
+   * fire, so the caller must skip rather than alert (mirrors the metric
+   * evaluator's zero-variance guard).
+   */
+  public static evaluate(input: {
+    observedPerMinute: number;
+    stats: CountBaselineStats;
+    sigmaCount: number;
+    method: AnomalyDetectionMethod;
+    filterType: FilterType | undefined;
+  }): CountAnomalyEvaluation | null {
+    const isMedianMad: boolean =
+      input.method === AnomalyDetectionMethod.MedianMad;
+    const center: number = isMedianMad ? input.stats.median : input.stats.mean;
+    const spread: number = isMedianMad
+      ? input.stats.madSigma
+      : input.stats.stddev;
+
+    if (!Number.isFinite(spread) || spread <= 0) {
+      return null;
+    }
+
+    const expectedHigh: number = center + input.sigmaCount * spread;
+    const expectedLow: number = center - input.sigmaCount * spread;
+    const observedSigma: number = (input.observedPerMinute - center) / spread;
+
+    const isHighBreach: boolean = input.observedPerMinute > expectedHigh;
+    const isLowBreach: boolean = input.observedPerMinute < expectedLow;
+
+    let breaches: boolean = false;
+    switch (input.filterType) {
+      case FilterType.AnomalouslyHigh:
+        breaches = isHighBreach;
+        break;
+      case FilterType.AnomalouslyLow:
+        breaches = isLowBreach;
+        break;
+      case FilterType.Anomalous:
+        breaches = isHighBreach || isLowBreach;
+        break;
+      default:
+        breaches = false;
+    }
+
+    return {
+      breaches,
+      observedSigma,
+      expectedHigh,
+      expectedLow,
+      center,
+      spread,
+    };
+  }
+
+  private static medianOf(values: Array<number>): number {
+    const sorted: Array<number> = [...values].sort((a: number, b: number) => {
+      return a - b;
+    });
+    const mid: number = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+      return (sorted[mid - 1]! + sorted[mid]!) / 2;
+    }
+    return sorted[mid]!;
+  }
+}

package/Server/Utils/Monitor/Criteria/DnsMonitorCriteria.ts

@@ -7,15 +7,21 @@ import {
 } from "../../../../Types/Monitor/CriteriaFilter";
 import DnsMonitorResponse from "../../../../Types/Monitor/DnsMonitor/DnsMonitorResponse";
 import ProbeMonitorResponse from "../../../../Types/Probe/ProbeMonitorResponse";
-import EvaluateOverTime from "./EvaluateOverTime";
+import EvaluateOverTime, { OverTimeCriteriaValue } from "./EvaluateOverTime";
 import CaptureSpan from "../../Telemetry/CaptureSpan";
-import logger from "../../Logger";
 
 export default class DnsMonitorCriteria {
   @CaptureSpan()
   public static async isMonitorInstanceCriteriaFilterMet(input: {
     dataToProcess: DataToProcess;
     criteriaFilter: CriteriaFilter;
+    /*
+     * The monitor's monitoringInterval cron. Over-time filters use it to
+     * work out how many samples a fully covered window should hold, so a
+     * monitor that has only just started is not mistaken for one whose
+     * whole window is breaching.
+     */
+    monitoringInterval?: string | undefined;
   }): Promise<string | null> {
     let threshold: number | string | undefined | null =
       input.criteriaFilter.value;
@@ -26,37 +32,36 @@ export default class DnsMonitorCriteria {
     const dnsResponse: DnsMonitorResponse | undefined =
       dataToProcess.dnsResponse;
 
-    let overTimeValue: Array<number | boolean> | number | boolean | undefined =
-      undefined;
-
-    if (
-      input.criteriaFilter.evaluateOverTime &&
-      input.criteriaFilter.evaluateOverTimeOptions
-    ) {
-      try {
-        overTimeValue = await EvaluateOverTime.getValueOverTime({
-          projectId: (input.dataToProcess as ProbeMonitorResponse).projectId,
-          monitorId: input.dataToProcess.monitorId!,
-          evaluateOverTimeOptions: input.criteriaFilter.evaluateOverTimeOptions,
-          metricType: input.criteriaFilter.checkOn,
-        });
+    const overTime: OverTimeCriteriaValue =
+      await EvaluateOverTime.getOverTimeValueForCriteriaFilter({
+        projectId: (input.dataToProcess as ProbeMonitorResponse).projectId,
+        monitorId: input.dataToProcess.monitorId!,
+        criteriaFilter: input.criteriaFilter,
+        monitoringInterval: input.monitoringInterval,
+      });
 
-        if (Array.isArray(overTimeValue) && overTimeValue.length === 0) {
-          overTimeValue = undefined;
-        }
-      } catch (err) {
-        logger.error(
-          `Error in getting over time value for ${input.criteriaFilter.checkOn}`,
-        );
-        logger.error(err);
-        overTimeValue = undefined;
-      }
+    /*
+     * The window could not back this over-time filter (nothing recorded yet,
+     * or the monitor has not been running long enough to cover it). Return
+     * the decision the no-data policy already made instead of falling
+     * through to the value that arrived with this one check - that fallback
+     * is what let "all values over the last N minutes" fire off a single
+     * bad reading.
+     */
+    if (overTime.earlyReturn) {
+      return overTime.earlyReturn.result;
     }
 
+    const overTimeValue:
+      | Array<number | boolean>
+      | number
+      | boolean
+      | undefined = overTime.value;
+
     // Check if DNS is online
     if (input.criteriaFilter.checkOn === CheckOn.DnsIsOnline) {
       const currentIsOnline: boolean | Array<boolean> =
-        (overTimeValue as Array<boolean>) ||
+        (overTimeValue as Array<boolean>) ??
         (input.dataToProcess as ProbeMonitorResponse).isOnline;
 
       return CompareCriteria.compareCriteriaBoolean({
@@ -74,9 +79,9 @@ export default class DnsMonitorCriteria {
       }
 
       const currentResponseTime: number | Array<number> =
-        (overTimeValue as Array<number>) ||
-        dnsResponse?.responseTimeInMs ||
-        (input.dataToProcess as ProbeMonitorResponse).responseTimeInMs;
+        (overTimeValue as Array<number>) ??
+        (dnsResponse?.responseTimeInMs ||
+          (input.dataToProcess as ProbeMonitorResponse).responseTimeInMs);
 
       if (currentResponseTime === null || currentResponseTime === undefined) {
         return null;