@oneuptime/common 12.0.34 → 13.0.0

package/Server/Utils/Monitor/MonitorCriteriaEvaluator.ts

@@ -100,6 +100,11 @@ import MonitorStepPodmanMonitor from "../../../Types/Monitor/MonitorStepPodmanMo
 import MonitorStepProxmoxMonitor from "../../../Types/Monitor/MonitorStepProxmoxMonitor";
 import MonitorStepCephMonitor from "../../../Types/Monitor/MonitorStepCephMonitor";
 import MonitorStepDockerSwarmMonitor from "../../../Types/Monitor/MonitorStepDockerSwarmMonitor";
+import MetricValueFormatter from "../../../Utils/Monitor/MetricValueFormatter";
+import { getKubernetesMetricByMetricName } from "../../../Types/Monitor/KubernetesMetricCatalog";
+import { getProxmoxMetricByMetricName } from "../../../Types/Monitor/ProxmoxMetricCatalog";
+import { getCephMetricByMetricName } from "../../../Types/Monitor/CephMetricCatalog";
+import { getDockerSwarmMetricByMetricName } from "../../../Types/Monitor/DockerSwarmMetricCatalog";
 
 /**
  * A cross-signal deep link into a telemetry explorer, plus the scope
@@ -1433,13 +1438,28 @@ ${contextBlock}
       return null;
     }
 
+    const unitHeuristicMetricName: string | undefined =
+      MonitorCriteriaEvaluator.metricNameForUnitHeuristics({
+        metricName: ctx.metricName,
+        isFormula: ctx.isFormula,
+      });
+
     const lines: Array<string> = [];
     lines.push(`- Metric: \`${ctx.metricName}\``);
     if (ctx.alias) {
       lines.push(`- Alias: \`${ctx.alias}\``);
     }
-    if (ctx.unit) {
-      lines.push(`- Unit: ${ctx.unit}`);
+    /*
+     * Spell the unit out — "Bytes", not the UCUM "By" the exporter wrote —
+     * and drop the line entirely for units that name no dimension, so a
+     * ratio metric no longer reports the bare "Unit: 1".
+     */
+    const readableUnit: string | null = MetricValueFormatter.getReadableUnit(
+      ctx.unit,
+      unitHeuristicMetricName,
+    );
+    if (readableUnit) {
+      lines.push(`- Unit: ${readableUnit}`);
     }
     if (ctx.aggregationType) {
       lines.push(`- Aggregation: ${ctx.aggregationType}`);
@@ -1459,8 +1479,16 @@ ${contextBlock}
     if (ctx.components && ctx.components.length > 0) {
       const componentLines: Array<string> = ctx.components.map(
         (component: MetricComponent) => {
-          const unitSuffix: string = component.unit
-            ? ` — unit: ${component.unit}`
+          const componentUnit: string | null =
+            MetricValueFormatter.getReadableUnit(
+              component.unit,
+              MonitorCriteriaEvaluator.metricNameForUnitHeuristics({
+                metricName: component.name,
+                isFormula: component.isFormula,
+              }),
+            );
+          const unitSuffix: string = componentUnit
+            ? ` — unit: ${componentUnit}`
             : "";
           const typeSuffix: string = component.isFormula ? " (formula)" : "";
           return `  - \`${component.alias}\` = \`${component.name}\`${typeSuffix}${unitSuffix}`;
@@ -1504,6 +1532,7 @@ ${contextBlock}
           totalSamples: ctx.totalSamplesInWindow,
           unit: ctx.unit,
           metricName: ctx.metricName,
+          unitHeuristicMetricName: unitHeuristicMetricName,
           alias: ctx.alias,
           components: ctx.components || [],
         })}`,
@@ -1575,6 +1604,11 @@ ${contextBlock}
     totalSamples?: number | undefined;
     unit: string | null;
     metricName: string;
+    /**
+     * The metric name to reason about, or undefined for a formula.
+     * See MonitorCriteriaEvaluator.metricNameForUnitHeuristics.
+     */
+    unitHeuristicMetricName: string | undefined;
     alias: string;
     components: Array<MetricComponent>;
   }): string {
@@ -1628,17 +1662,20 @@ ${contextBlock}
       "Value",
     ];
 
+    /*
+     * The component columns carry no unit in their header any more. Each
+     * cell now names the unit it actually landed on, and auto-scaling
+     * means neighbouring rows can land on different ones — a header that
+     * read "a (By)" over cells reading "900 KB" and "1.2 MB" states a
+     * unit that neither row uses. The configured unit is not lost: the
+     * Components bullet list above the table still records it.
+     */
     for (const component of input.components) {
-      const label: string = component.unit
-        ? `${component.alias} (${component.unit})`
-        : component.alias;
-      headerCells.push(label);
+      headerCells.push(component.alias);
     }
 
     headerCells.push(...attrKeys);
 
-    const unitSuffix: string = input.unit ? ` ${input.unit}` : "";
-
     const headerRow: string = `| ${headerCells.join(" | ")} |`;
     const dividerRow: string = `| ${headerCells
       .map(() => {
@@ -1658,7 +1695,11 @@ ${contextBlock}
           `\`${timestampIso}\``,
           metricCell,
           aliasCell,
-          `${MonitorCriteriaEvaluator.formatNumberForDisplay(s.value)}${unitSuffix}`,
+          MetricValueFormatter.format({
+            value: s.value,
+            unit: input.unit,
+            metricName: input.unitHeuristicMetricName,
+          }),
         ];
 
         for (const component of input.components) {
@@ -1668,11 +1709,24 @@ ${contextBlock}
             return cv.alias === component.alias;
           });
           if (match && typeof match.value === "number") {
-            const componentUnitSuffix: string = component.unit
-              ? ` ${component.unit}`
-              : "";
+            /*
+             * Each component keeps its OWN unit. Component values are
+             * indexed off the per-query series and never go through the
+             * sample→threshold-unit conversion the main Value column
+             * does, so they are in the component's legendUnit — mixing
+             * units across the row is deliberate, and is why every cell
+             * has to say which one it is in.
+             */
             cells.push(
-              `${MonitorCriteriaEvaluator.formatNumberForDisplay(match.value)}${componentUnitSuffix}`,
+              MetricValueFormatter.format({
+                value: match.value,
+                unit: component.unit,
+                metricName:
+                  MonitorCriteriaEvaluator.metricNameForUnitHeuristics({
+                    metricName: component.name,
+                    isFormula: component.isFormula,
+                  }),
+              }),
             );
           } else {
             cells.push("-");
@@ -1722,16 +1776,6 @@ ${contextBlock}
     return `${input.breachingCount} sample${input.breachingCount === 1 ? "" : "s"} breached the threshold.`;
   }
 
-  private static formatNumberForDisplay(value: number): string {
-    if (!Number.isFinite(value)) {
-      return String(value);
-    }
-    if (Number.isInteger(value)) {
-      return value.toString();
-    }
-    return Number(value.toFixed(2)).toString();
-  }
-
   private static buildMetricExplorerDeepLink(input: {
     monitor: Monitor;
     ctx: MetricCriteriaContext;
@@ -1923,6 +1967,27 @@ ${contextBlock}
     };
   }
 
+  /**
+   * The metric name to hand a unit heuristic, or undefined when there
+   * isn't one.
+   *
+   * `MetricCriteriaContext.metricName` and `MetricComponent.name` are the
+   * FORMULA EXPRESSION when the criteria (or the component) targets a
+   * formula — MetricMonitorCriteria.buildContext falls back to
+   * `metricFormula`. The only thing a name is used for downstream is
+   * ValueFormatter.isFractionMetric, which asks whether the name ends in
+   * `.utilization` / `_ratio` / `_percent` and multiplies a "1"-unit value
+   * by 100 when it does. A formula written as `a / b_ratio` ends in
+   * `_ratio` and would silently be reported at 100× its real value, so a
+   * formula gets no name at all.
+   */
+  private static metricNameForUnitHeuristics(input: {
+    metricName: string | undefined;
+    isFormula: boolean | undefined;
+  }): string | undefined {
+    return input.isFormula ? undefined : input.metricName;
+  }
+
   private static formatScopeDroppedHint(dropped: Array<string>): string {
     if (dropped.length === 0) {
       return "";
@@ -1931,6 +1996,61 @@ ${contextBlock}
     return ` _(scope partially carried — not applied: ${dropped.join(", ")})_`;
   }
 
+  /**
+   * The unit for a value in a per-platform "Affected Resources" table.
+   *
+   * These rows are NOT the same numbers as the criteria's breaching
+   * samples: the worker collects them with a raw `MetricService.findBy`
+   * scan and never runs them through MetricResultUnitConverter, so they
+   * are in the metric's NATIVE unit while the criteria threshold was
+   * compared in the user's chosen display unit. Labelling them with the
+   * query's legendUnit would therefore attach a confidently wrong unit to
+   * a correct number.
+   *
+   * The catalog is the right source precisely because it also declares
+   * the native unit. It is the same lookup, on the same metric name, that
+   * the worker already ran to resolve `metricFriendlyName`, so the unit
+   * shown here can never disagree with the metric name shown beside it.
+   */
+  private static getPlatformMetricUnit(input: {
+    platform: "kubernetes" | "proxmox" | "dockerSwarm" | "ceph";
+    metricName: string;
+  }): string | undefined {
+    switch (input.platform) {
+      case "kubernetes":
+        return getKubernetesMetricByMetricName(input.metricName)?.unit;
+      case "proxmox":
+        return getProxmoxMetricByMetricName(input.metricName)?.unit;
+      case "dockerSwarm":
+        return getDockerSwarmMetricByMetricName(input.metricName)?.unit;
+      case "ceph":
+        return getCephMetricByMetricName(input.metricName)?.unit;
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * Render one cell of a platform breakdown table's Value column.
+   *
+   * Bold, because that is how these tables have always drawn the value —
+   * it is the one number in the row a reader scans for.
+   */
+  private static formatPlatformResourceValue(input: {
+    platform: "kubernetes" | "proxmox" | "dockerSwarm" | "ceph";
+    metricName: string;
+    value: number;
+  }): string {
+    return `**${MetricValueFormatter.format({
+      value: input.value,
+      unit: MonitorCriteriaEvaluator.getPlatformMetricUnit({
+        platform: input.platform,
+        metricName: input.metricName,
+      }),
+      metricName: input.metricName,
+    })}**`;
+  }
+
   private static async buildKubernetesRootCauseContext(input: {
     dataToProcess: DataToProcess;
     monitorStep: MonitorStep;
@@ -2071,7 +2191,13 @@ ${contextBlock}
           cells.push(resource.nodeName ? `\`${resource.nodeName}\`` : "-");
         }
 
-        cells.push(`**${resource.metricValue}**`);
+        cells.push(
+          MonitorCriteriaEvaluator.formatPlatformResourceValue({
+            platform: "kubernetes",
+            metricName: breakdown.metricName,
+            value: resource.metricValue,
+          }),
+        );
 
         resourceLines.push(`| ${cells.join(" | ")} |`);
       }
@@ -2478,7 +2604,13 @@ ${contextBlock}
             : "-";
 
           resourceLines.push(
-            `| ${resourceCell} | ${typeCell} | ${nodeCell} | **${resource.metricValue}** |`,
+            `| ${resourceCell} | ${typeCell} | ${nodeCell} | ${MonitorCriteriaEvaluator.formatPlatformResourceValue(
+              {
+                platform: "proxmox",
+                metricName: breakdown.metricName,
+                value: resource.metricValue,
+              },
+            )} |`,
           );
         }
 
@@ -2640,7 +2772,13 @@ ${contextBlock}
             : "-";
 
           resourceLines.push(
-            `| ${taskCell} | ${serviceCell} | ${nodeCell} | **${resource.metricValue}** |`,
+            `| ${taskCell} | ${serviceCell} | ${nodeCell} | ${MonitorCriteriaEvaluator.formatPlatformResourceValue(
+              {
+                platform: "dockerSwarm",
+                metricName: breakdown.metricName,
+                value: resource.metricValue,
+              },
+            )} |`,
           );
         }
 
@@ -2865,7 +3003,13 @@ ${contextBlock}
             : "-";
 
           resourceLines.push(
-            `| ${daemonCell} | ${poolCell} | ${hostCell} | **${resource.metricValue}** |`,
+            `| ${daemonCell} | ${poolCell} | ${hostCell} | ${MonitorCriteriaEvaluator.formatPlatformResourceValue(
+              {
+                platform: "ceph",
+                metricName: breakdown.metricName,
+                value: resource.metricValue,
+              },
+            )} |`,
           );
         }
 
@@ -2914,6 +3058,27 @@ ${contextBlock}
     const metricName: string = breakdown.metricName;
     const lines: Array<string> = [];
 
+    /*
+     * The top resource's value, in the unit the catalog says the metric
+     * is actually reported in.
+     *
+     * The three "is at N%" sentences below used to hardcode that percent
+     * sign. Two of the three metrics they fire for are not percentages at
+     * all — k8s.node.memory.usage and k8s.node.filesystem.usage are
+     * `bytes`, so a node holding 8 GiB reported "memory usage is at
+     * 8589934592.0%" — and the third, k8s.node.cpu.utilization, is the
+     * kubeletstats cores gauge that four other places in this repo warn
+     * is misnamed, so 1.4 cores in use read as "1.4% CPU utilization".
+     */
+    const topResourceValue: string = MetricValueFormatter.format({
+      value: topResource.metricValue,
+      unit: MonitorCriteriaEvaluator.getPlatformMetricUnit({
+        platform: "kubernetes",
+        metricName: metricName,
+      }),
+      metricName: metricName,
+    });
+
     if (
       metricName === "k8s.container.restarts" ||
       metricName.includes("restart")
@@ -2923,7 +3088,7 @@ ${contextBlock}
       );
       if (topResource.containerName) {
         lines.push(
-          `The container \`${topResource.containerName}\` in pod \`${topResource.podName || "unknown"}\` has restarted **${topResource.metricValue}** times.`,
+          `The container \`${topResource.containerName}\` in pod \`${topResource.podName || "unknown"}\` has restarted **${topResourceValue}** times.`,
         );
       }
       lines.push(
@@ -2959,7 +3124,7 @@ ${contextBlock}
       lines.push(`One or more nodes have transitioned to a NotReady state.`);
       if (topResource.nodeName) {
         lines.push(
-          `Node \`${topResource.nodeName}\` is reporting NotReady (value: ${topResource.metricValue}).`,
+          `Node \`${topResource.nodeName}\` is reporting NotReady (value: ${topResourceValue}).`,
         );
       }
       lines.push(
@@ -2986,7 +3151,7 @@ ${contextBlock}
       lines.push(`Node CPU utilization has exceeded the configured threshold.`);
       if (topResource.nodeName) {
         lines.push(
-          `Node \`${topResource.nodeName}\` is at **${topResource.metricValue.toFixed(1)}%** CPU utilization.`,
+          `Node \`${topResource.nodeName}\` is at **${topResourceValue}** CPU utilization.`,
         );
       }
       lines.push(
@@ -3007,7 +3172,7 @@ ${contextBlock}
       );
       if (topResource.nodeName) {
         lines.push(
-          `Node \`${topResource.nodeName}\` memory usage is at **${topResource.metricValue.toFixed(1)}%**.`,
+          `Node \`${topResource.nodeName}\` memory usage is at **${topResourceValue}**.`,
         );
       }
       lines.push(
@@ -3025,7 +3190,7 @@ ${contextBlock}
       );
       if (topResource.workloadName) {
         lines.push(
-          `${topResource.workloadType || "Deployment"} \`${topResource.workloadName}\` has **${topResource.metricValue}** unavailable replica(s).`,
+          `${topResource.workloadType || "Deployment"} \`${topResource.workloadName}\` has **${topResourceValue}** unavailable replica(s).`,
         );
       }
       lines.push(
@@ -3041,7 +3206,7 @@ ${contextBlock}
       lines.push(`Kubernetes Job has failed pods.`);
       if (topResource.workloadName) {
         lines.push(
-          `Job \`${topResource.workloadName}\` has **${topResource.metricValue}** failed pod(s).`,
+          `Job \`${topResource.workloadName}\` has **${topResourceValue}** failed pod(s).`,
         );
       }
       lines.push(
@@ -3060,7 +3225,7 @@ ${contextBlock}
       );
       if (topResource.nodeName) {
         lines.push(
-          `Node \`${topResource.nodeName}\` filesystem usage is at **${topResource.metricValue.toFixed(1)}%**.`,
+          `Node \`${topResource.nodeName}\` filesystem usage is at **${topResourceValue}**.`,
         );
       }
       lines.push(
@@ -3076,7 +3241,7 @@ ${contextBlock}
       lines.push(`DaemonSet has misscheduled or unavailable nodes.`);
       if (topResource.workloadName) {
         lines.push(
-          `DaemonSet \`${topResource.workloadName}\` has **${topResource.metricValue}** misscheduled node(s).`,
+          `DaemonSet \`${topResource.workloadName}\` has **${topResourceValue}** misscheduled node(s).`,
         );
       }
       lines.push(

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${