@oneuptime/common 12.0.33 → 13.0.0

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

@@ -7,26 +7,123 @@ import {
 } from "../../../../Types/Monitor/CriteriaFilter";
 import Typeof from "../../../../Types/Typeof";
 import CaptureSpan from "../../Telemetry/CaptureSpan";
+import MetricValueFormatter from "../../../../Utils/Monitor/MetricValueFormatter";
 
 export default class CompareCriteria {
+  /*
+   * Reduce an evaluation window to the value(s) a threshold is actually
+   * compared against.
+   *
+   * Before this existed, every comparator branched on `AnyValue` and let
+   * EVERY other evaluation type fall through to `.every()`. That silently
+   * turned Average, Sum, Maximum Value and Minimum Value — all four
+   * offered in the criteria UI and all four stored on real monitors — into
+   * "All Values". A user who asked to be paged on the five-minute AVERAGE
+   * was instead paged only when every single sample breached, which is a
+   * strictly rarer event and never the one they asked for.
+   *
+   * Returns a single-element array for the reducing aggregations so the
+   * caller compares against the aggregate, and the untouched window for
+   * the two set-quantifier types.
+   */
+  public static reduceWindow(data: {
+    values: Array<number>;
+    evaluationType?: EvaluateOverTimeType | undefined;
+  }): Array<number> {
+    const values: Array<number> = data.values;
+
+    if (values.length === 0) {
+      return values;
+    }
+
+    switch (data.evaluationType) {
+      case EvaluateOverTimeType.Average: {
+        const sum: number = values.reduce((a: number, b: number) => {
+          return a + b;
+        }, 0);
+        return [sum / values.length];
+      }
+      case EvaluateOverTimeType.Sum:
+        return [
+          values.reduce((a: number, b: number) => {
+            return a + b;
+          }, 0),
+        ];
+      case EvaluateOverTimeType.MaximumValue:
+        return [Math.max(...values)];
+      case EvaluateOverTimeType.MunimumValue:
+        return [Math.min(...values)];
+      default:
+        // AnyValue / AllValues quantify over the window itself.
+        return values;
+    }
+  }
+
+  /*
+   * The one place a numeric criteria filter decides whether it is met.
+   *
+   * `AnyValue` is an existential quantifier, everything else is universal
+   * once `reduceWindow` has collapsed the reducing aggregations to a
+   * single sample — so "Average > 90" is `[avg].every(v => v > 90)`, which
+   * is just `avg > 90`.
+   */
+  private static evaluateWindow(data: {
+    value: number | Array<number>;
+    evaluationType?: EvaluateOverTimeType | undefined;
+    predicate: (value: number) => boolean;
+  }): boolean {
+    if (!Array.isArray(data.value)) {
+      return data.predicate(data.value);
+    }
+
+    const values: Array<number> = CompareCriteria.reduceWindow({
+      values: data.value,
+      evaluationType: data.evaluationType,
+    });
+
+    if (values.length === 0) {
+      return false;
+    }
+
+    if (data.evaluationType === EvaluateOverTimeType.AnyValue) {
+      return values.some(data.predicate);
+    }
+
+    return values.every(data.predicate);
+  }
+
+  /*
+   * The samples that actually satisfied the filter.
+   *
+   * Only used to render the root cause. `getCompareMessage` used to print
+   * the WHOLE window and then assert every printed number breached the
+   * threshold, so a real alert read "is 72.35, 81.54, 79.95, 91.53, 87.73 %
+   * which is greater than 90 %" — four of those five are below 90.
+   */
+  public static getBreachingValues(data: {
+    values: Array<number>;
+    evaluationType?: EvaluateOverTimeType | undefined;
+    predicate: (value: number) => boolean;
+  }): Array<number> {
+    return CompareCriteria.reduceWindow({
+      values: data.values,
+      evaluationType: data.evaluationType,
+    }).filter(data.predicate);
+  }
+
   @CaptureSpan()
   public static greaterThan(data: {
     value: number | Array<number>;
     evaluationType?: EvaluateOverTimeType | undefined;
     threshold: number;
   }): boolean {
-    if (Array.isArray(data.value)) {
-      if (data.evaluationType === EvaluateOverTimeType.AnyValue) {
-        return data.value.some((value: number) => {
-          return value > data.threshold;
-        });
-      }
-      return data.value.every((value: number) => {
+    return CompareCriteria.evaluateWindow({
+      value: data.value,
+      evaluationType: data.evaluationType,
+      predicate: (value: number) => {
         return value > data.threshold;
-      });
-    }
-
-    return data.value > data.threshold;
+      },
+    });
   }
 
   @CaptureSpan()
@@ -77,18 +174,13 @@ export default class CompareCriteria {
     evaluationType?: EvaluateOverTimeType | undefined;
     threshold: number;
   }): boolean {
-    if (Array.isArray(data.value)) {
-      if (data.evaluationType === EvaluateOverTimeType.AnyValue) {
-        return data.value.some((value: number) => {
-          return value < data.threshold;
-        });
-      }
-      return data.value.every((value: number) => {
+    return CompareCriteria.evaluateWindow({
+      value: data.value,
+      evaluationType: data.evaluationType,
+      predicate: (value: number) => {
         return value < data.threshold;
-      });
-    }
-
-    return data.value < data.threshold;
+      },
+    });
   }
 
   @CaptureSpan()
@@ -97,18 +189,13 @@ export default class CompareCriteria {
     evaluationType?: EvaluateOverTimeType | undefined;
     threshold: number;
   }): boolean {
-    if (Array.isArray(data.value)) {
-      if (data.evaluationType === EvaluateOverTimeType.AnyValue) {
-        return data.value.some((value: number) => {
-          return value >= data.threshold;
-        });
-      }
-      return data.value.every((value: number) => {
+    return CompareCriteria.evaluateWindow({
+      value: data.value,
+      evaluationType: data.evaluationType,
+      predicate: (value: number) => {
         return value >= data.threshold;
-      });
-    }
-
-    return data.value >= data.threshold;
+      },
+    });
   }
 
   @CaptureSpan()
@@ -117,18 +204,13 @@ export default class CompareCriteria {
     evaluationType?: EvaluateOverTimeType | undefined;
     threshold: number;
   }): boolean {
-    if (Array.isArray(data.value)) {
-      if (data.evaluationType === EvaluateOverTimeType.AnyValue) {
-        return data.value.some((value: number) => {
-          return value <= data.threshold;
-        });
-      }
-      return data.value.every((value: number) => {
+    return CompareCriteria.evaluateWindow({
+      value: data.value,
+      evaluationType: data.evaluationType,
+      predicate: (value: number) => {
         return value <= data.threshold;
-      });
-    }
-
-    return data.value <= data.threshold;
+      },
+    });
   }
 
   @CaptureSpan()
@@ -137,18 +219,13 @@ export default class CompareCriteria {
     evaluationType?: EvaluateOverTimeType | undefined;
     threshold: number;
   }): boolean {
-    if (Array.isArray(data.value)) {
-      if (data.evaluationType === EvaluateOverTimeType.AnyValue) {
-        return data.value.some((value: number) => {
-          return value === data.threshold;
-        });
-      }
-      return data.value.every((value: number) => {
+    return CompareCriteria.evaluateWindow({
+      value: data.value,
+      evaluationType: data.evaluationType,
+      predicate: (value: number) => {
         return value === data.threshold;
-      });
-    }
-
-    return data.value === data.threshold;
+      },
+    });
   }
 
   @CaptureSpan()
@@ -157,18 +234,13 @@ export default class CompareCriteria {
     evaluationType?: EvaluateOverTimeType | undefined;
     threshold: number;
   }): boolean {
-    if (Array.isArray(data.value)) {
-      if (data.evaluationType === EvaluateOverTimeType.AnyValue) {
-        return data.value.some((value: number) => {
-          return value !== data.threshold;
-        });
-      }
-      return data.value.every((value: number) => {
+    return CompareCriteria.evaluateWindow({
+      value: data.value,
+      evaluationType: data.evaluationType,
+      predicate: (value: number) => {
         return value !== data.threshold;
-      });
-    }
-
-    return data.value !== data.threshold;
+      },
+    });
   }
 
   @CaptureSpan()
@@ -403,6 +475,15 @@ export default class CompareCriteria {
     criteriaFilter: CriteriaFilter;
     metricDisplayName?: string | undefined;
     unit?: string | undefined;
+    /**
+     * The metric NAME, when there is a real one. Distinct from
+     * metricDisplayName, which is the formula expression for a formula
+     * criteria and is only ever used as a label: this one feeds
+     * ValueFormatter.isFractionMetric, which would read the trailing
+     * `_ratio` of a formula like `a / b_ratio` as a signal to multiply
+     * the value by 100. Callers pass it only for plain metric criteria.
+     */
+    metricName?: string | undefined;
   }): string | null {
     if (data.value === null || data.value === undefined) {
       return null;
@@ -428,6 +509,7 @@ export default class CompareCriteria {
           criteriaFilter: data.criteriaFilter,
           metricDisplayName: data.metricDisplayName,
           unit: data.unit,
+          metricName: data.metricName,
         });
       }
 
@@ -450,6 +532,7 @@ export default class CompareCriteria {
           criteriaFilter: data.criteriaFilter,
           metricDisplayName: data.metricDisplayName,
           unit: data.unit,
+          metricName: data.metricName,
         });
       }
 
@@ -472,6 +555,7 @@ export default class CompareCriteria {
           criteriaFilter: data.criteriaFilter,
           metricDisplayName: data.metricDisplayName,
           unit: data.unit,
+          metricName: data.metricName,
         });
       }
 
@@ -494,6 +578,7 @@ export default class CompareCriteria {
           criteriaFilter: data.criteriaFilter,
           metricDisplayName: data.metricDisplayName,
           unit: data.unit,
+          metricName: data.metricName,
         });
       }
 
@@ -516,6 +601,7 @@ export default class CompareCriteria {
           criteriaFilter: data.criteriaFilter,
           metricDisplayName: data.metricDisplayName,
           unit: data.unit,
+          metricName: data.metricName,
         });
       }
 
@@ -538,6 +624,7 @@ export default class CompareCriteria {
           criteriaFilter: data.criteriaFilter,
           metricDisplayName: data.metricDisplayName,
           unit: data.unit,
+          metricName: data.metricName,
         });
       }
 
@@ -554,9 +641,19 @@ export default class CompareCriteria {
     criteriaFilter: CriteriaFilter;
     metricDisplayName?: string | undefined;
     unit?: string | undefined;
+    /**
+     * The metric NAME, when there is a real one. Distinct from
+     * metricDisplayName, which is the formula expression for a formula
+     * criteria and is only ever used as a label: this one feeds
+     * ValueFormatter.isFractionMetric, which would read the trailing
+     * `_ratio` of a formula like `a / b_ratio` as a signal to multiply
+     * the value by 100. Callers pass it only for plain metric criteria.
+     */
+    metricName?: string | undefined;
   }): string {
     // CPU Percent over the last 5 minutes is 10 which is less than the threshold of 20
     let message: string = "";
+    let breachSummary: string = "";
 
     let evaluationType: EvaluateOverTimeType | undefined =
       data.criteriaFilter.evaluateOverTimeOptions?.evaluateOverTimeType;
@@ -566,12 +663,34 @@ export default class CompareCriteria {
         data.criteriaFilter.metricMonitorOptions.metricAggregationType;
     }
 
-    if (evaluationType === EvaluateOverTimeType.AnyValue) {
-      message += "Any value of";
-    }
-
-    if (evaluationType === EvaluateOverTimeType.AllValues) {
-      message += "All values of";
+    /*
+     * Name the quantifier or the aggregation. Before this, only the two
+     * set quantifiers were named and the four reducing aggregations
+     * produced a bare "Metric Value is 82.62 which is greater than 90",
+     * which reads as a contradiction unless you already know the number
+     * shown is a five-minute average.
+     */
+    switch (evaluationType) {
+      case EvaluateOverTimeType.AnyValue:
+        message += "Any value of";
+        break;
+      case EvaluateOverTimeType.AllValues:
+        message += "All values of";
+        break;
+      case EvaluateOverTimeType.Average:
+        message += "The average of";
+        break;
+      case EvaluateOverTimeType.Sum:
+        message += "The sum of";
+        break;
+      case EvaluateOverTimeType.MaximumValue:
+        message += "The maximum of";
+        break;
+      case EvaluateOverTimeType.MunimumValue:
+        message += "The minimum of";
+        break;
+      default:
+        break;
     }
 
     /*
@@ -600,39 +719,114 @@ export default class CompareCriteria {
       message += ` over the last ${data.criteriaFilter.evaluateOverTimeOptions.timeValueInMinutes} minutes`;
     }
 
-    const unitSuffix: string = data.unit ? ` ${data.unit}` : "";
+    /*
+     * A metric value is written the way the dashboard writes it —
+     * "1.07 GB", "1.5 sec", "25.34%" — rather than as raw digits with a
+     * raw UCUM code glued on. Only two of the ~35 callers pass a unit at
+     * all (MetricMonitorCriteria and DatabaseMonitorCriteria); everything
+     * else carries its unit inside the CheckOn label ("Response Time (in
+     * ms)") and must keep its exact digits, so an absent unit leaves this
+     * sentence byte-for-byte as it was.
+     *
+     * MetricValueFormatter also subsumes the unit-suppression rules this
+     * block used to spell out by hand: OTel's dimensionless "1" (which
+     * made a CLS breach read "is 0.31 1 which is greater than or equal to
+     * 0.25 1") and UCUM's annotation-only "{cpu}" / "{packets}" both
+     * disappear, and a fraction metric still carrying "1" is rendered as
+     * the percentage it means.
+     *
+     * The unit rides each NUMBER instead of the sentence, because
+     * auto-scaling can land two samples in the same sentence on different
+     * scales — "is 900 KB, 1.2 MB" — which one trailing suffix cannot
+     * express.
+     */
+    const withUnit: ((value: number) => string) | undefined =
+      MetricValueFormatter.hasDisplayableUnit(data.unit, data.metricName)
+        ? (value: number): string => {
+            return MetricValueFormatter.format({
+              value: value,
+              unit: data.unit,
+              metricName: data.metricName,
+            });
+          }
+        : undefined;
 
     if (
       data.criteriaFilter.filterType !== FilterType.True &&
       data.criteriaFilter.filterType !== FilterType.False
     ) {
+      /*
+       * Print the samples that actually breached, not the whole window.
+       *
+       * `AnyValue` is an existential quantifier: it is met when ONE sample
+       * crosses the threshold. Printing the entire window and then
+       * asserting "which is greater than 90" produced the sentence a real
+       * customer received — "is 72.35, 81.54, 79.95, 91.53, 87.73 % which
+       * is greater than 90 %" — in which four of the five listed numbers
+       * are below the threshold the sentence claims they all exceed.
+       *
+       * For every other evaluation type the reported set and the compared
+       * set are the same thing (a reducing aggregation collapses to one
+       * value; AllValues requires all of them), so this narrowing is a
+       * no-op and the existing wording is preserved exactly.
+       */
+      const reportedValues:
+        | Array<number | boolean>
+        | number
+        | boolean
+        | string = CompareCriteria.getReportedValues({
+        values: data.values,
+        threshold: data.threshold,
+        filterType: data.criteriaFilter.filterType as FilterType,
+        evaluationType: evaluationType,
+      });
+
       const formattedValues: string = CompareCriteria.formatCriteriaValues(
-        data.values,
+        reportedValues,
+        withUnit,
       );
 
-      message += ` is ${formattedValues}${unitSuffix}`;
+      message += ` is ${formattedValues}`;
 
       message += " which is";
+
+      /*
+       * How much of the window actually breached.
+       *
+       * Without it "Any value ... is 91.53 % which is greater than 90 %"
+       * is true but hides the thing the reader needs in order to judge
+       * whether to get out of bed: whether that was one transient sample
+       * or the whole five minutes. One-in-five is a spike; five-in-five is
+       * an outage. Only added when the two counts differ, so a fully
+       * breaching window keeps the shorter sentence.
+       */
+      if (
+        Array.isArray(data.values) &&
+        Array.isArray(reportedValues) &&
+        reportedValues.length < data.values.length
+      ) {
+        breachSummary = ` ${reportedValues.length} of ${data.values.length} samples in the evaluation window breached this threshold.`;
+      }
     }
 
     switch (data.criteriaFilter.filterType) {
       case FilterType.GreaterThan:
-        message += ` greater than ${CompareCriteria.formatSingleValue(data.threshold)}${unitSuffix}. `;
+        message += ` greater than ${CompareCriteria.formatSingleValue(data.threshold, withUnit)}. `;
         break;
       case FilterType.GreaterThanOrEqualTo:
-        message += ` greater than or equal to ${CompareCriteria.formatSingleValue(data.threshold)}${unitSuffix}. `;
+        message += ` greater than or equal to ${CompareCriteria.formatSingleValue(data.threshold, withUnit)}. `;
         break;
       case FilterType.LessThan:
-        message += ` less than ${CompareCriteria.formatSingleValue(data.threshold)}${unitSuffix}. `;
+        message += ` less than ${CompareCriteria.formatSingleValue(data.threshold, withUnit)}. `;
         break;
       case FilterType.LessThanOrEqualTo:
-        message += ` less than or equal to ${CompareCriteria.formatSingleValue(data.threshold)}${unitSuffix}. `;
+        message += ` less than or equal to ${CompareCriteria.formatSingleValue(data.threshold, withUnit)}. `;
         break;
       case FilterType.NotEqualTo:
-        message += ` not equal to ${CompareCriteria.formatSingleValue(data.threshold)}${unitSuffix}. `;
+        message += ` not equal to ${CompareCriteria.formatSingleValue(data.threshold, withUnit)}. `;
         break;
       case FilterType.EqualTo:
-        message += ` equal to ${CompareCriteria.formatSingleValue(data.threshold)}${unitSuffix}. `;
+        message += ` equal to ${CompareCriteria.formatSingleValue(data.threshold, withUnit)}. `;
         break;
       case FilterType.Contains:
         message += ` contains ${CompareCriteria.formatSingleValue(data.threshold)}. `;
@@ -654,11 +848,119 @@ export default class CompareCriteria {
         break;
     }
 
-    return message.trim();
+    return `${message.trim()}${breachSummary}`;
   }
 
+  /*
+   * Narrow the window down to what the message should quote.
+   *
+   * Only `AnyValue` needs narrowing — see the comment at the call site.
+   * A reducing aggregation is collapsed to its single aggregate so the
+   * sentence quotes the average it actually compared, not the raw samples.
+   * If nothing is found to breach (a caller rendering a message for a
+   * filter that did not match, or a non-numeric window) the original
+   * values are returned unchanged rather than an empty list, so the
+   * message degrades to its previous behaviour instead of to "is ".
+   */
+  private static getReportedValues(data: {
+    values: Array<number | boolean> | number | boolean | string;
+    threshold: number | string | boolean;
+    filterType: FilterType;
+    evaluationType?: EvaluateOverTimeType | undefined;
+  }): Array<number | boolean> | number | boolean | string {
+    if (!Array.isArray(data.values)) {
+      return data.values;
+    }
+
+    if (typeof data.threshold !== Typeof.Number) {
+      return data.values;
+    }
+
+    const numericValues: Array<number> = data.values.filter(
+      (value: number | boolean): value is number => {
+        return typeof value === Typeof.Number && Number.isFinite(value);
+      },
+    );
+
+    if (numericValues.length !== data.values.length) {
+      return data.values;
+    }
+
+    const predicate: ((value: number) => boolean) | null =
+      CompareCriteria.getNumericPredicate({
+        filterType: data.filterType,
+        threshold: data.threshold as number,
+      });
+
+    if (!predicate) {
+      return data.values;
+    }
+
+    const breaching: Array<number> = CompareCriteria.getBreachingValues({
+      values: numericValues,
+      evaluationType: data.evaluationType,
+      predicate: predicate,
+    });
+
+    if (breaching.length === 0) {
+      return data.values;
+    }
+
+    return breaching;
+  }
+
+  /*
+   * The comparison a numeric filter type performs, as a predicate.
+   *
+   * Kept next to the comparator methods it mirrors so the two cannot
+   * drift: a filter type added to `compareCriteriaNumbers` without a case
+   * here falls back to quoting the whole window, which is the old
+   * behaviour rather than a wrong one.
+   */
+  private static getNumericPredicate(data: {
+    filterType: FilterType;
+    threshold: number;
+  }): ((value: number) => boolean) | null {
+    switch (data.filterType) {
+      case FilterType.GreaterThan:
+        return (value: number) => {
+          return value > data.threshold;
+        };
+      case FilterType.GreaterThanOrEqualTo:
+        return (value: number) => {
+          return value >= data.threshold;
+        };
+      case FilterType.LessThan:
+        return (value: number) => {
+          return value < data.threshold;
+        };
+      case FilterType.LessThanOrEqualTo:
+        return (value: number) => {
+          return value <= data.threshold;
+        };
+      case FilterType.EqualTo:
+        return (value: number) => {
+          return value === data.threshold;
+        };
+      case FilterType.NotEqualTo:
+        return (value: number) => {
+          return value !== data.threshold;
+        };
+      default:
+        return null;
+    }
+  }
+
+  /*
+   * `withUnit`, when supplied, is how a NUMBER is rendered — unit
+   * included. It is threaded down rather than applied to the finished
+   * string because the string is not always one number: a large window
+   * collapses to "N samples between X and Y", and both X and Y need the
+   * unit of their own scale.
+   */
   private static formatCriteriaValues(
     values: Array<number | boolean> | number | boolean | string,
+    withUnit?: ((value: number) => string) | undefined,
   ): string {
     if (Array.isArray(values)) {
       /*
@@ -673,7 +975,7 @@ export default class CompareCriteria {
       if (values.length <= MAX_INLINE) {
         return values
           .map((value: number | boolean) => {
-            return CompareCriteria.formatSingleValue(value);
+            return CompareCriteria.formatSingleValue(value, withUnit);
           })
           .join(", ");
       }
@@ -689,24 +991,26 @@ export default class CompareCriteria {
         const max: number = Math.max(...numericValues);
         return `${numericValues.length} samples between ${CompareCriteria.formatSingleValue(
           min,
-        )} and ${CompareCriteria.formatSingleValue(max)}`;
+          withUnit,
+        )} and ${CompareCriteria.formatSingleValue(max, withUnit)}`;
       }
 
       // Fall back to a truncated list when not all values are numeric
       const head: string = values
         .slice(0, MAX_INLINE)
         .map((value: number | boolean) => {
-          return CompareCriteria.formatSingleValue(value);
+          return CompareCriteria.formatSingleValue(value, withUnit);
         })
         .join(", ");
       return `${head}, … (${values.length} values total)`;
     }
 
-    return CompareCriteria.formatSingleValue(values);
+    return CompareCriteria.formatSingleValue(values, withUnit);
   }
 
   private static formatSingleValue(
     value: number | boolean | string | null | undefined,
+    withUnit?: ((value: number) => string) | undefined,
   ): string {
     if (value === null || value === undefined) {
       return "unknown";
@@ -715,6 +1019,10 @@ export default class CompareCriteria {
     if (typeof value === Typeof.Number) {
       const numericValue: number = value as number;
 
+      if (withUnit) {
+        return withUnit(numericValue);
+      }
+
       if (Number.isInteger(numericValue)) {
         return numericValue.toString();
       }