@oneuptime/common 12.0.33 → 13.0.0

package/Server/Utils/Monitor/MonitorCriteriaExpectationBuilder.ts

@@ -2,10 +2,21 @@ import {
   CriteriaFilter,
   FilterType,
 } from "../../../Types/Monitor/CriteriaFilter";
+import MetricValueFormatter from "../../../Utils/Monitor/MetricValueFormatter";
+
+/**
+ * How a criteria's values are displayed: the unit, and the metric name
+ * the formatter's fraction / epoch rules are keyed on.
+ */
+export interface CriteriaDisplayOptions {
+  unit?: string | undefined;
+  metricName?: string | undefined;
+}
 
 export default class MonitorCriteriaExpectationBuilder {
   public static getCriteriaFilterDescription(
     criteriaFilter: CriteriaFilter,
+    options?: CriteriaDisplayOptions,
   ): string {
     const parts: Array<string> = [criteriaFilter.checkOn];
 
@@ -14,15 +25,51 @@ export default class MonitorCriteriaExpectationBuilder {
     }
 
     if (criteriaFilter.value !== undefined && criteriaFilter.value !== null) {
-      parts.push(String(criteriaFilter.value));
+      const formatted: string | number =
+        MonitorCriteriaExpectationBuilder.formatThreshold(
+          criteriaFilter.value,
+          options,
+        ) ?? criteriaFilter.value;
+
+      parts.push(String(formatted));
     }
 
     return parts.join(" ").trim();
   }
 
+  /*
+   * The threshold, rendered exactly as an observed value would be — or
+   * returned untouched when it cannot be.
+   *
+   * Untouched covers three cases, and each matters: no unit was resolved
+   * (every non-metric checkOn, whose unit lives in its CheckOn label), the
+   * threshold is a string (the Contains / StartsWith family, which must
+   * quote what the user typed), or it is not a finite number.
+   */
+  private static formatThreshold(
+    value: string | number | undefined,
+    options?: CriteriaDisplayOptions,
+  ): string | number | undefined {
+    if (!options?.unit) {
+      return value;
+    }
+
+    const numeric: number = Number(value);
+
+    if (typeof value === "boolean" || !Number.isFinite(numeric)) {
+      return value;
+    }
+
+    return MetricValueFormatter.format({
+      value: numeric,
+      unit: options.unit,
+      metricName: options.metricName,
+    });
+  }
+
   public static describeCriteriaExpectation(
     criteriaFilter: CriteriaFilter,
-    options?: { unit?: string | undefined },
+    options?: CriteriaDisplayOptions,
   ): string | null {
     if (!criteriaFilter.filterType) {
       return null;
@@ -30,35 +77,61 @@ export default class MonitorCriteriaExpectationBuilder {
 
     let expectation: string;
 
+    /*
+     * Render the threshold the way the observed value is rendered, so the
+     * two halves of one sentence cannot describe one quantity differently.
+     * Reformatting only the observation produced "recorded latest 1.07 GB
+     * (expected to be greater than 1000000000 By)".
+     *
+     * A NON-numeric threshold falls back to the previous text verbatim —
+     * `criteriaFilter.value` is `string | number | undefined`, and the
+     * string filter types below must keep quoting exactly what the user
+     * typed. So must a threshold with no unit: `formatThreshold` is only
+     * installed when a unit was resolved, which happens for the two metric
+     * checkOns and nothing else.
+     */
     const value: string | number | undefined = criteriaFilter.value;
 
+    /*
+     * The threshold as the six value-comparison cases below should print
+     * it, unit included. Only those six get it: the string comparisons
+     * quote what the user typed, and the heartbeat windows carry their own
+     * "minutes" — formatting their value produced "within 5 sec minutes".
+     */
+    const comparedValue: string | number | undefined =
+      MonitorCriteriaExpectationBuilder.formatThreshold(value, options);
+
     /*
      * Suffix numeric-threshold comparisons with the metric's display unit
      * (e.g. "greater than 5 sec") so the threshold reads in the same unit
      * as the observed value. Only the value-comparison filter types below
      * carry a numeric threshold — the others (empty, boolean, heartbeat
      * windows, …) supply their own wording and get no suffix.
+     *
+     * When the value was formatted above it already carries its unit, so
+     * this suffix collapses to empty and the unit is not printed twice.
      */
-    const unitSuffix: string = options?.unit ? ` ${options.unit}` : "";
+    const unitSuffix: string =
+      options?.unit && comparedValue === value ? ` ${options.unit}` : "";
 
     switch (criteriaFilter.filterType) {
       case FilterType.GreaterThan:
-        expectation = `to be greater than ${value}${unitSuffix}`;
+        expectation = `to be greater than ${comparedValue}${unitSuffix}`;
         break;
       case FilterType.GreaterThanOrEqualTo:
-        expectation = `to be greater than or equal to ${value}${unitSuffix}`;
+        expectation = `to be greater than or equal to ${comparedValue}${unitSuffix}`;
         break;
       case FilterType.LessThan:
-        expectation = `to be less than ${value}${unitSuffix}`;
+        expectation = `to be less than ${comparedValue}${unitSuffix}`;
         break;
       case FilterType.LessThanOrEqualTo:
-        expectation = `to be less than or equal to ${value}${unitSuffix}`;
+        expectation = `to be less than or equal to ${comparedValue}${unitSuffix}`;
         break;
       case FilterType.EqualTo:
-        expectation = `to equal ${value}${unitSuffix}`;
+        expectation = `to equal ${comparedValue}${unitSuffix}`;
         break;
       case FilterType.NotEqualTo:
-        expectation = `to not equal ${value}${unitSuffix}`;
+        expectation = `to not equal ${comparedValue}${unitSuffix}`;
         break;
       case FilterType.Contains:
         expectation = `to contain ${value}`;

package/Server/Utils/Monitor/MonitorCriteriaMessageBuilder.ts

@@ -59,17 +59,19 @@ export default class MonitorCriteriaMessageBuilder {
      * the observed value — "recorded latest 0.06 sec (expected to be greater
      * than 5 sec)" rather than the unitless "0.06 (expected ... 5)".
      */
-    const metricDisplayUnit: string | undefined =
-      MonitorCriteriaObservationBuilder.getMetricValueDisplayUnit({
-        criteriaFilter: input.criteriaFilter,
-        dataToProcess: input.dataToProcess,
-        monitorStep: input.monitorStep,
-      });
+    const metricDisplay: {
+      unit: string | undefined;
+      metricName: string | undefined;
+    } = MonitorCriteriaObservationBuilder.getMetricValueDisplayContext({
+      criteriaFilter: input.criteriaFilter,
+      dataToProcess: input.dataToProcess,
+      monitorStep: input.monitorStep,
+    });
 
     const expectation: string | null =
       MonitorCriteriaExpectationBuilder.describeCriteriaExpectation(
         input.criteriaFilter,
-        { unit: metricDisplayUnit },
+        metricDisplay,
       );
 
     const observation: string | null =
@@ -89,9 +91,16 @@ export default class MonitorCriteriaMessageBuilder {
     }
 
     if (expectation) {
+      /*
+       * Both halves of this sentence quote the same threshold, so both
+       * must render it the same way — otherwise it reads "Metric Value
+       * greater than 1000000000 did not satisfy the configured condition
+       * (expected to be greater than 1 GB)".
+       */
       const description: string =
         MonitorCriteriaExpectationBuilder.getCriteriaFilterDescription(
           input.criteriaFilter,
+          metricDisplay,
         );
 
       return `${description} did not satisfy the configured condition (${expectation}).`;

package/Server/Utils/Monitor/MonitorCriteriaMessageFormatter.ts

@@ -136,9 +136,24 @@ export default class MonitorCriteriaMessageFormatter {
     return null;
   }
 
+  /**
+   * "latest 1.07 GB (min 900 KB, max 1.07 GB) across 3 data points".
+   *
+   * `format`, when supplied, renders ONE value — unit included — and is
+   * applied to latest, min and max independently. That independence is the
+   * point: auto-scaling can land min and max on different rungs of the
+   * ladder, which a single trailing unit suffix cannot express. It is the
+   * same reason CompareCriteria puts the unit on each number rather than on
+   * the sentence, and using the same callback in both places is what stops
+   * the evaluation log and the alert email describing one sample two ways.
+   *
+   * Without it the `unit` string is appended as before, so the caller that
+   * passes no unit at all (execution time) stays byte-identical.
+   */
   public static summarizeNumericSeries(
     values: Array<number>,
     unit?: string | undefined,
+    format?: ((value: number) => string) | undefined,
   ): string | null {
     if (!values.length) {
       return null;
@@ -156,29 +171,26 @@ export default class MonitorCriteriaMessageFormatter {
      */
     const unitSuffix: string = unit ? ` ${unit}` : "";
 
-    const latestFormatted: string | null =
-      MonitorCriteriaMessageFormatter.formatNumber(latest, {
-        maximumFractionDigits: 2,
-      });
+    const renderValue: (value: number) => string = (value: number): string => {
+      if (format) {
+        return format(value);
+      }
+
+      const formatted: string | null =
+        MonitorCriteriaMessageFormatter.formatNumber(value, {
+          maximumFractionDigits: 2,
+        });
+
+      return `${formatted ?? value}${unitSuffix}`;
+    };
 
-    let summary: string = `latest ${latestFormatted ?? latest}${unitSuffix}`;
+    let summary: string = `latest ${renderValue(latest)}`;
 
     if (values.length > 1) {
       const min: number = Math.min(...values);
       const max: number = Math.max(...values);
 
-      const minFormatted: string | null =
-        MonitorCriteriaMessageFormatter.formatNumber(min, {
-          maximumFractionDigits: 2,
-        });
-      const maxFormatted: string | null =
-        MonitorCriteriaMessageFormatter.formatNumber(max, {
-          maximumFractionDigits: 2,
-        });
-
-      summary += ` (min ${minFormatted ?? min}${unitSuffix}, max ${
-        maxFormatted ?? max
-      }${unitSuffix})`;
+      summary += ` (min ${renderValue(min)}, max ${renderValue(max)})`;
     }
 
     summary += ` across ${values.length} data point${

package/Server/Utils/Monitor/MonitorCriteriaObservationBuilder.ts

@@ -41,6 +41,7 @@ import MetricQueryConfigData from "../../../Types/Metrics/MetricQueryConfigData"
 import MetricFormulaConfigData from "../../../Types/Metrics/MetricFormulaConfigData";
 import MetricsViewConfig from "../../../Types/Metrics/MetricsViewConfig";
 import MetricUnitUtil from "../../../Utils/MetricUnitUtil";
+import MetricValueFormatter from "../../../Utils/Monitor/MetricValueFormatter";
 
 export default class MonitorCriteriaObservationBuilder {
   public static describeFilterObservation(input: {
@@ -1220,18 +1221,33 @@ export default class MonitorCriteriaObservationBuilder {
      * that unit alongside the numbers so the message reads "latest 0.06 sec"
      * instead of the unitless "latest 0.06".
      */
-    const displayUnit: string | undefined =
-      MonitorCriteriaObservationBuilder.resolveMetricUnits({
-        criteriaFilter: input.criteriaFilter,
-        dataToProcess: input.dataToProcess,
-        monitorStep: input.monitorStep,
-        alias: metricValues.alias,
-      }).displayUnit;
+    const resolvedUnits: {
+      displayUnit: string | undefined;
+      metricName: string | undefined;
+    } = MonitorCriteriaObservationBuilder.resolveMetricUnits({
+      criteriaFilter: input.criteriaFilter,
+      dataToProcess: input.dataToProcess,
+      monitorStep: input.monitorStep,
+      alias: metricValues.alias,
+    });
 
+    /*
+     * The same renderer the fired-alert email uses. Before this, a breach
+     * that CompareCriteria wrote into the email as "1.07 GB" appeared in
+     * the monitor's own evaluation log as "1073741824.00 By" — one sample,
+     * two descriptions, on two screens a reader compares.
+     */
     const summary: string | null =
       MonitorCriteriaMessageFormatter.summarizeNumericSeries(
         displayValues,
-        displayUnit,
+        resolvedUnits.displayUnit,
+        (value: number): string => {
+          return MetricValueFormatter.format({
+            value: value,
+            unit: resolvedUnits.displayUnit,
+            metricName: resolvedUnits.metricName,
+          });
+        },
       );
 
     if (!summary) {
@@ -1304,6 +1320,18 @@ export default class MonitorCriteriaObservationBuilder {
     sampleUnit: string | undefined;
     thresholdUnit: string | undefined;
     displayUnit: string | undefined;
+    /**
+     * The metric NAME, for the two decisions MetricValueFormatter cannot
+     * make from a unit alone: whether a "1"-unit value is a fraction to
+     * render as a percent, and whether a "seconds"-unit value is really an
+     * epoch that must skip the duration ladder.
+     *
+     * Undefined for a formula. A formula's "name" is its expression, and an
+     * expression ending in `_ratio` would trip the fraction heuristic into
+     * reporting every value at 100x — the same guard
+     * MonitorCriteriaEvaluator.metricNameForUnitHeuristics applies.
+     */
+    metricName: string | undefined;
   } {
     const thresholdUnit: string | undefined =
       input.criteriaFilter.metricMonitorOptions?.thresholdUnit || undefined;
@@ -1317,6 +1345,7 @@ export default class MonitorCriteriaObservationBuilder {
         sampleUnit: undefined,
         thresholdUnit,
         displayUnit: thresholdUnit,
+        metricName: undefined,
       };
     }
 
@@ -1355,35 +1384,42 @@ export default class MonitorCriteriaObservationBuilder {
       nativeUnitFromMap ||
       undefined;
 
+    const displayUnit: string | undefined = thresholdUnit || sampleUnit;
+
     return {
       sampleUnit,
       thresholdUnit,
       displayUnit: MonitorCriteriaObservationBuilder.normalizeDisplayUnit(
-        thresholdUnit || sampleUnit,
+        displayUnit,
+        rawMetricName,
       ),
+      metricName: rawMetricName,
     };
   }
 
   /*
-   * Suppress units that would read as noise next to a raw number. OTel's
-   * dimensionless "1" marks ratio metrics whose samples are fractions in
-   * [0, 1]; rendering "0.06 1" is both ugly and misleading (it is not 1% —
-   * it is 6%). Returning undefined leaves the number unlabelled, matching
-   * the pre-unit behavior for that specific case. Any real unit passes
-   * through unchanged.
+   * Suppress units that name no dimension, so they never reach a reader
+   * next to a number.
+   *
+   * This used to be a hand-rolled rule that dropped only the literal "1",
+   * and it drifted from the one CompareCriteria applies to the very same
+   * sample: a ratio metric's evaluation log read a bare "latest 0.06"
+   * while the alert email for the identical value said "6.00%". It also
+   * let UCUM's "{restarts}" and the platform catalogs' "count" / "ratio"
+   * through, none of which mean anything to a reader.
+   *
+   * MetricValueFormatter owns that rule now. Note it is name-AWARE where
+   * the old one was not: "1" on a `.utilization` metric is a real
+   * dimension (a fraction to be shown as a percent), so it survives here
+   * and the formatter turns it into "%".
    */
   private static normalizeDisplayUnit(
     unit: string | undefined,
+    metricName?: string | undefined,
   ): string | undefined {
-    if (!unit || !unit.trim()) {
-      return undefined;
-    }
-
-    if (unit.trim() === "1") {
-      return undefined;
-    }
-
-    return unit;
+    return MetricValueFormatter.hasDisplayableUnit(unit, metricName)
+      ? unit
+      : undefined;
   }
 
   /*
@@ -1399,6 +1435,24 @@ export default class MonitorCriteriaObservationBuilder {
     dataToProcess: DataToProcess;
     monitorStep: MonitorStep;
   }): string | undefined {
+    return MonitorCriteriaObservationBuilder.getMetricValueDisplayContext(input)
+      .unit;
+  }
+
+  /**
+   * The unit AND the metric name a criteria's values are displayed in.
+   *
+   * The expectation clause needs both, not just the unit: it renders the
+   * threshold through the same MetricValueFormatter as the observation, and
+   * the formatter's fraction and epoch-timestamp rules are keyed on the
+   * name. Without it, "recorded latest 6.00%" would be followed by
+   * "(expected to be greater than 0.9)".
+   */
+  public static getMetricValueDisplayContext(input: {
+    criteriaFilter: CriteriaFilter;
+    dataToProcess: DataToProcess;
+    monitorStep: MonitorStep;
+  }): { unit: string | undefined; metricName: string | undefined } {
     /*
      * Database Health thresholds are typed in the metric's own unit, which
      * only the catalog knows - without this the expectation clause reads
@@ -1412,13 +1466,17 @@ export default class MonitorCriteriaObservationBuilder {
         ? getDatabaseMetricByMetricType(metricType)
         : null;
 
-      return MonitorCriteriaObservationBuilder.normalizeDisplayUnit(
-        definition?.unit,
-      );
+      return {
+        unit: MonitorCriteriaObservationBuilder.normalizeDisplayUnit(
+          definition?.unit,
+        ),
+        // Catalog units are explicit; no name-based heuristic is wanted.
+        metricName: undefined,
+      };
     }
 
     if (input.criteriaFilter.checkOn !== CheckOn.MetricValue) {
-      return undefined;
+      return { unit: undefined, metricName: undefined };
     }
 
     const metricValues: {
@@ -1430,12 +1488,17 @@ export default class MonitorCriteriaObservationBuilder {
       monitorStep: input.monitorStep,
     });
 
-    return MonitorCriteriaObservationBuilder.resolveMetricUnits({
+    const resolved: {
+      displayUnit: string | undefined;
+      metricName: string | undefined;
+    } = MonitorCriteriaObservationBuilder.resolveMetricUnits({
       criteriaFilter: input.criteriaFilter,
       dataToProcess: input.dataToProcess,
       monitorStep: input.monitorStep,
       alias: metricValues?.alias ?? null,
-    }).displayUnit;
+    });
+
+    return { unit: resolved.displayUnit, metricName: resolved.metricName };
   }
 
   private static getSnmpResponse(input: {
@@ -1743,28 +1806,24 @@ export default class MonitorCriteriaObservationBuilder {
     }
   }
 
+  /*
+   * A Database Health metric carries an explicit catalog unit, and
+   * DatabaseMonitorCriteria already hands that same unit to CompareCriteria
+   * for the fired-alert email. Rendering it here through anything else made
+   * one byte count read three ways in one product: the email said
+   * "1.07 GB" (decimal, via MetricValueFormatter), this observation said
+   * "1.00 GB" (formatBytes divides by 1024 but labels the rungs SI), and
+   * the expectation clause beside it said "1000000000 bytes".
+   *
+   * formatBytes stays for the server-monitor memory and disk observations,
+   * where the values come from BasicMetrics with no unit metadata at all
+   * and 1024 is the right convention for RAM and volumes.
+   */
   private static formatDatabaseMetricValue(
     value: number,
     unit: string,
   ): string {
-    if (unit === "%") {
-      return (
-        MonitorCriteriaMessageFormatter.formatPercentage(value) ?? String(value)
-      );
-    }
-
-    if (unit === "bytes") {
-      return (
-        MonitorCriteriaMessageFormatter.formatBytes(value) ?? String(value)
-      );
-    }
-
-    const formatted: string =
-      MonitorCriteriaMessageFormatter.formatNumber(value, {
-        maximumFractionDigits: 2,
-      }) ?? String(value);
-
-    return unit ? `${formatted} ${unit}` : formatted;
+    return MetricValueFormatter.format({ value: value, unit: unit });
   }
 
   private static describeDatabaseCollectionErrorObservation(input: {

package/Server/Utils/Monitor/MonitorIncident.ts

@@ -27,6 +27,7 @@ import logger, { LogAttributes } from "../Logger";
 import CaptureSpan from "../Telemetry/CaptureSpan";
 import DataToProcess from "./DataToProcess";
 import MonitorTemplateUtil from "./MonitorTemplateUtil";
+import SeriesContextEnricher from "./SeriesContextEnricher";
 import MonitorDependencySuppression, {
   DependencySuppressionResult,
 } from "./MonitorDependencySuppression";
@@ -597,13 +598,28 @@ export default class MonitorIncident {
               seriesLabels,
             });
 
-          incident.title = MonitorTemplateUtil.processTemplateString({
-            value: criteriaIncident.title,
-            storageMap,
+          /*
+           * Render the criteria's template, then make it say WHICH
+           * series it is about. Mirrors MonitorAlert exactly - the two
+           * must agree, or the same breach reads differently depending
+           * on whether the criteria was configured to raise an alert or
+           * an incident. See SeriesContextEnricher for why this is not
+           * done inside the template itself.
+           */
+          incident.title = SeriesContextEnricher.enrichTitle({
+            title: MonitorTemplateUtil.processTemplateString({
+              value: criteriaIncident.title,
+              storageMap,
+            }),
+            seriesLabels,
           });
-          incident.description = MonitorTemplateUtil.processTemplateString({
-            value: criteriaIncident.description,
-            storageMap,
+          incident.description = SeriesContextEnricher.enrichDescription({
+            description: MonitorTemplateUtil.processTemplateString({
+              value: criteriaIncident.description,
+              storageMap,
+            }),
+            seriesLabels,
+            monitorType: input.monitor.monitorType,
           });
 
           /*

package/Server/Utils/Monitor/MonitorTemplateUtil.ts

@@ -32,6 +32,8 @@ import ExternalStatusPageMonitorResponse, {
 } from "../../../Types/Monitor/ExternalStatusPageMonitor/ExternalStatusPageMonitorResponse";
 import MetricMonitorResponse from "../../../Types/Monitor/MetricMonitor/MetricMonitorResponse";
 import Typeof from "../../../Types/Typeof";
+import SeriesDebugHints from "../../../Types/Monitor/SeriesContext/SeriesDebugHints";
+import SeriesLabelDisplay from "../../../Types/Monitor/SeriesContext/SeriesLabelDisplay";
 import VMUtil from "../VM/VMAPI";
 import DataToProcess from "./DataToProcess";
 import logger from "../Logger";
@@ -627,6 +629,33 @@ export default class MonitorTemplateUtil {
       storageMap["seriesLabels"] = data.seriesLabels;
     }
 
+    /*
+     * Ready-made renderings of the series identity.
+     *
+     * These are set unconditionally - to "" when the monitor is not
+     * grouped, or when its labels carry no usable value - and that is
+     * the whole point. `VMUtil.replaceValueInPlace` leaves a placeholder
+     * it cannot resolve in the output verbatim, so a title written as
+     * `"Pod CPU high{{seriesResourceSuffix}}"` would otherwise render
+     * with the braces still in it on any monitor without a group-by.
+     * Always defining them makes the variables safe to use in a shipped
+     * template that has to work for grouped and ungrouped monitors
+     * alike.
+     */
+    storageMap["seriesResourceSuffix"] = SeriesLabelDisplay.buildTitleSuffix(
+      data.seriesLabels,
+    );
+    storageMap["seriesResourceSummary"] = SeriesLabelDisplay.buildInlineSummary(
+      data.seriesLabels,
+    );
+    storageMap["seriesResourceBlock"] = SeriesLabelDisplay.buildMarkdownBlock(
+      data.seriesLabels,
+    );
+    storageMap["seriesDebugCommands"] = SeriesDebugHints.buildMarkdownBlock({
+      monitorType: data.monitorType,
+      seriesLabels: data.seriesLabels,
+    });
+
     /*
      * Monitor identity fields. Always exposed (when a monitor is provided),
      * independent of monitorType, so templates like `{{monitorName}}` work