@oneuptime/common 14.0.3 → 14.0.5

package/Utils/MetricUnitUtil.ts

@@ -15,6 +15,11 @@ interface UnitDefinition {
   label: string;
   aliases: Array<string>;
   toCanonical: number;
+  /*
+   * A unit the family can CONVERT but that the threshold / legend unit
+   * pickers never offer. See the binary byte units below for why.
+   */
+  isConversionOnly?: boolean | undefined;
 }
 
 /*
@@ -59,6 +64,61 @@ const byteUnits: Array<UnitDefinition> = [
     aliases: ["pb", "petabyte", "petabytes", "pby"],
     toCanonical: 1e15,
   },
+
+  /*
+   * Binary (IEC) byte units — powers of 1024, not 1000. OpenTelemetry
+   * spells them in UCUM ("KiBy", "MiBy"), and the vcenter receiver reports
+   * memory in them, so without these members a "MiBy" sample was in no
+   * family at all: it could not be converted into a "GB" threshold (the
+   * value passed through unchanged, about a thousand times off) and the
+   * notification formatter could not scale it ("1048576 MiB" instead of
+   * "1.1 TB").
+   *
+   * CONVERSION-ONLY, deliberately. The threshold and legend unit pickers
+   * (CriteriaFilter, MetricAlias) build their options from
+   * getCompatibleUnits, whose byte list is the six decimal units — a
+   * contract MetricUnitUtil.test pins. Listing five near-duplicates
+   * ("MB" next to "MiB") in every bytes dropdown would clutter it for
+   * every metric, while the conversions below are what actually fixes
+   * the numbers. So the pickers keep treating a native "MiBy" exactly as
+   * they did before (a single raw-unit option, free-text legend), and
+   * only convertToMetricUnit / getFamilyBaseUnit see these members.
+   */
+  {
+    value: "KiB",
+    label: "Kibibytes (KiB)",
+    aliases: ["kib", "kiby", "kibibyte", "kibibytes"],
+    toCanonical: 1024,
+    isConversionOnly: true,
+  },
+  {
+    value: "MiB",
+    label: "Mebibytes (MiB)",
+    aliases: ["mib", "miby", "mebibyte", "mebibytes"],
+    toCanonical: 1024 ** 2,
+    isConversionOnly: true,
+  },
+  {
+    value: "GiB",
+    label: "Gibibytes (GiB)",
+    aliases: ["gib", "giby", "gibibyte", "gibibytes"],
+    toCanonical: 1024 ** 3,
+    isConversionOnly: true,
+  },
+  {
+    value: "TiB",
+    label: "Tebibytes (TiB)",
+    aliases: ["tib", "tiby", "tebibyte", "tebibytes"],
+    toCanonical: 1024 ** 4,
+    isConversionOnly: true,
+  },
+  {
+    value: "PiB",
+    label: "Pebibytes (PiB)",
+    aliases: ["pib", "piby", "pebibyte", "pebibytes"],
+    toCanonical: 1024 ** 5,
+    isConversionOnly: true,
+  },
 ];
 
 const timeUnits: Array<UnitDefinition> = [
@@ -167,24 +227,40 @@ function normalize(unit: string): string {
   return unit.trim().toLowerCase();
 }
 
+/*
+ * Which members a lookup may match. "offered" is what the unit pickers
+ * work with — every member except the conversion-only ones — and is what
+ * the picker-facing methods use, so a conversion-only native unit still
+ * reads to them as "no known family". "all" is for arithmetic.
+ */
+type MemberScope = "offered" | "all";
+
+function isInScope(definition: UnitDefinition, scope: MemberScope): boolean {
+  return scope === "all" || !definition.isConversionOnly;
+}
+
 function findDefinitionInFamily(
   unit: string,
   family: Array<UnitDefinition>,
+  scope: MemberScope,
 ): UnitDefinition | null {
   const normalized: string = normalize(unit);
   return (
     family.find((u: UnitDefinition) => {
-      return u.aliases.includes(normalized);
+      return isInScope(u, scope) && u.aliases.includes(normalized);
     }) || null
   );
 }
 
-function findFamily(unit: string): Array<UnitDefinition> | null {
+function findFamily(
+  unit: string,
+  scope: MemberScope,
+): Array<UnitDefinition> | null {
   if (!unit || !unit.trim()) {
     return null;
   }
   for (const family of allFamilies) {
-    if (findDefinitionInFamily(unit, family)) {
+    if (findDefinitionInFamily(unit, family, scope)) {
       return family;
     }
   }
@@ -205,14 +281,21 @@ export default class MetricUnitUtil {
       return [];
     }
 
-    const family: Array<UnitDefinition> | null = findFamily(metricUnit);
+    const family: Array<UnitDefinition> | null = findFamily(
+      metricUnit,
+      "offered",
+    );
     if (!family) {
       return [{ value: metricUnit, label: metricUnit }];
     }
 
-    return family.map((u: UnitDefinition) => {
-      return { value: u.value, label: u.label };
-    });
+    return family
+      .filter((u: UnitDefinition) => {
+        return isInScope(u, "offered");
+      })
+      .map((u: UnitDefinition) => {
+        return { value: u.value, label: u.label };
+      });
   }
 
   /*
@@ -233,7 +316,10 @@ export default class MetricUnitUtil {
       return undefined;
     }
 
-    const family: Array<UnitDefinition> | null = findFamily(metricUnit);
+    const family: Array<UnitDefinition> | null = findFamily(
+      metricUnit,
+      "offered",
+    );
     if (!family) {
       return metricUnit;
     }
@@ -241,6 +327,7 @@ export default class MetricUnitUtil {
     const def: UnitDefinition | null = findDefinitionInFamily(
       metricUnit,
       family,
+      "offered",
     );
 
     if (family === percentUnits && def?.value === "1") {
@@ -272,7 +359,7 @@ export default class MetricUnitUtil {
       return value;
     }
 
-    const family: Array<UnitDefinition> | null = findFamily(metricUnit);
+    const family: Array<UnitDefinition> | null = findFamily(metricUnit, "all");
     if (!family) {
       return value;
     }
@@ -280,10 +367,12 @@ export default class MetricUnitUtil {
     const fromDef: UnitDefinition | null = findDefinitionInFamily(
       fromUnit,
       family,
+      "all",
     );
     const metricDef: UnitDefinition | null = findDefinitionInFamily(
       metricUnit,
       family,
+      "all",
     );
 
     if (!fromDef || !metricDef) {
@@ -317,7 +406,7 @@ export default class MetricUnitUtil {
       return null;
     }
 
-    const family: Array<UnitDefinition> | null = findFamily(metricUnit);
+    const family: Array<UnitDefinition> | null = findFamily(metricUnit, "all");
     if (!family) {
       return null;
     }
@@ -335,6 +424,9 @@ export default class MetricUnitUtil {
    * Convenience: does the metric unit belong to a family we can offer
    * conversions for? When false, the UI should still render a dropdown,
    * but with just the raw unit.
+   *
+   * "Offer" is literal: a conversion-only unit ("MiBy") answers false, in
+   * step with getCompatibleUnits, which gives it no family list either.
    */
   public static hasCompatibleUnitFamily(
     metricUnit: string | undefined,
@@ -342,6 +434,6 @@ export default class MetricUnitUtil {
     if (!metricUnit || !metricUnit.trim()) {
       return false;
     }
-    return findFamily(metricUnit) !== null;
+    return findFamily(metricUnit, "offered") !== null;
   }
 }

package/Utils/Monitor/MetricValueFormatter.ts

@@ -35,22 +35,39 @@ import ValueFormatter from "../ValueFormatter";
  *     sample arrive carrying the unit "GB", and ValueFormatter has a
  *     ladder for "bytes" but not for "GB" — so 2500 of them rendered
  *     "2.5K GB" instead of "2.5 TB". Anything in a MetricUnitUtil family
- *     is converted to that family's base before the ladder runs.
+ *     is converted to that family's base before the ladder runs. That
+ *     includes the binary (IEC) byte units the vcenter receiver reports
+ *     memory in: 2048 "MiBy" is restated as 2147483648 bytes and reads
+ *     "2.15 GB", where it used to read "2048 MiB" and, for a large host,
+ *     "1048576 MiB".
  *
  *  3. UNITS WORTH HIDING. OTel's dimensionless "1" and UCUM's
  *     annotation-only units ("{restarts}", "{packets}") are not
  *     dimensions, and printing them produces the "0.06 1" that
  *     CompareCriteria and MonitorCriteriaObservationBuilder each grew
- *     their own guard against. That rule lives here now.
+ *     their own guard against. That rule lives here now — with one
+ *     exception: braces around a REAL, scalable unit ("{KiBy/s}", which
+ *     the vcenter receiver uses for throughput) are unwrapped rather than
+ *     hidden, because the value in them is a quantity, not a count.
  */
 export default class MetricValueFormatter {
   /*
    * UCUM annotation-only units — "{thread}", "{packets}", "{errors}".
    * The braces describe what is being counted; the value is a plain
    * count and the text inside them is not a unit a reader should see.
+   *
+   * Only reached for braces whose inner text is NOT itself a scalable
+   * unit: canonicalizeUnit has already unwrapped "{KiBy/s}" to "KiBy/s"
+   * (see unwrapScalableAnnotation), so what still matches here is a
+   * genuine annotation.
    */
   private static readonly annotationOnlyUnitPattern: RegExp = /^\{[^{}]*\}$/;
 
+  /*
+   * The same shape, capturing the inner text.
+   */
+  private static readonly bracedUnitPattern: RegExp = /^\{([^{}]*)\}$/;
+
   /*
    * The per-platform metric catalogs (Kubernetes, Ceph, Proxmox, Docker
    * Swarm) were written for humans reading a metric picker, so they spell
@@ -93,7 +110,8 @@ export default class MetricValueFormatter {
    * Whether `unit` names a real dimension for `metricName` — i.e. whether
    * it is worth attaching to a number at all. False for the empty unit,
    * for the dimensionless "1" on a non-fraction metric, and for
-   * annotation-only units.
+   * annotation-only units. True for a braced unit whose inner text is a
+   * scalable unit ("{KiBy/s}"), which format() renders as that unit.
    */
   public static hasDisplayableUnit(
     unit: string | null | undefined,
@@ -128,6 +146,8 @@ export default class MetricValueFormatter {
    *   format({ value: 1500, unit: "ms" })                  → "1.5 sec"
    *   format({ value: 3661, unit: "seconds" })             → "1.02 hours"
    *   format({ value: 1500000, unit: "By/s" })             → "1.5 MB/s"
+   *   format({ value: 2048, unit: "MiBy" })                → "2.15 GB"
+   *   format({ value: 2500000, unit: "{KiBy/s}" })         → "2.56 GB/s"
    *   format({ value: 0.2534, unit: "1",
    *            metricName: "system.cpu.utilization" })     → "25.34%"
    *   format({ value: 87.5, unit: "%" })                   → "87.50%"
@@ -139,6 +159,7 @@ export default class MetricValueFormatter {
    * A value with no dimension to report is left bare:
    *   format({ value: 1500 })                              → "1500"
    *   format({ value: 1500, unit: "{restarts}" })          → "1500"
+   *   format({ value: 1500, unit: "{errors/s}" })          → "1500"
    *   format({ value: 3.14159 })                           → "3.14"
    */
   public static format(input: {
@@ -198,7 +219,7 @@ export default class MetricValueFormatter {
      * becomes "m per s2" and "10*3/uL" becomes "10*3 per uL", both longer
      * and less recognisable than what the exporter wrote. getCompactUnit
      * keeps the slash and still expands what is worth expanding
-     * ("Cel" → "°C", "KiBy" → "KiB").
+     * ("Cel" → "°C").
      */
     const unitSymbol: string =
       ValueFormatter.getCompactUnit(unit, formatOptions) || unit;
@@ -229,11 +250,12 @@ export default class MetricValueFormatter {
   }
 
   /*
-   * Trim the unit and rewrite the catalogs' English spellings of "no
-   * dimension" into the UCUM ones the rest of the pipeline understands.
-   * Anything else is returned untouched — including its casing, which
-   * matters because an unrecognised unit is echoed verbatim next to the
-   * value ("5 widgets", not "5 Widgets").
+   * Trim the unit, unwrap a braced scalable unit ("{KiBy/s}" → "KiBy/s"),
+   * and rewrite the catalogs' English spellings of "no dimension" into the
+   * UCUM ones the rest of the pipeline understands. Anything else is
+   * returned untouched — including its casing, which matters because an
+   * unrecognised unit is echoed verbatim next to the value ("5 widgets",
+   * not "5 Widgets").
    */
   private static canonicalizeUnit(unit: string | null | undefined): string {
     const trimmed: string = (unit || "").trim();
@@ -242,10 +264,40 @@ export default class MetricValueFormatter {
       return "";
     }
 
+    const unwrapped: string =
+      MetricValueFormatter.unwrapScalableAnnotation(trimmed);
+
     const alias: string | undefined =
-      MetricValueFormatter.informalUnitAliases[trimmed.toLowerCase()];
+      MetricValueFormatter.informalUnitAliases[unwrapped.toLowerCase()];
+
+    return alias === undefined ? unwrapped : alias;
+  }
+
+  /*
+   * The vcenter receiver declares its throughput metrics as "{KiBy/s}":
+   * UCUM annotation braces around what is, in fact, a real unit. The
+   * annotation rule used to hide it, so 2500000 of them — about 2.56 GB/s
+   * of disk traffic — reached the inbox as a bare "2500000".
+   *
+   * So a braced unit is unwrapped when, and only when, its inner text is
+   * something this formatter can SCALE: a unit with a ladder, a member of
+   * a MetricUnitUtil family whose base has one ("KiBy", "GB", "min"), or
+   * a rate whose numerator is one of those ("KiBy/s", "By/s"). Every
+   * genuine annotation stays hidden exactly as before — "{restarts}",
+   * "{cpu}", "{packets/s}" and "{errors/s}" name no unit a ladder knows,
+   * so they keep rendering as the bare count.
+   */
+  private static unwrapScalableAnnotation(unit: string): string {
+    const match: RegExpMatchArray | null = unit.match(
+      MetricValueFormatter.bracedUnitPattern,
+    );
+    const inner: string = (match?.[1] || "").trim();
+
+    if (!inner) {
+      return unit;
+    }
 
-    return alias === undefined ? trimmed : alias;
+    return MetricValueFormatter.toScalableUnit(1, inner) ? inner : unit;
   }
 
   /**
@@ -273,8 +325,9 @@ export default class MetricValueFormatter {
    *   - it already has one ("bytes", "ms", "s", "ns");
    *   - it is a rate whose NUMERATOR does ("By/s" → scale the bytes, keep
    *     the "/s"), which is how 1500000 By/s reads "1.5 MB/s";
-   *   - it is a prefixed member of a MetricUnitUtil family ("GB", "hours"),
-   *     in which case the value is converted into that family's base first.
+   *   - it is a prefixed member of a MetricUnitUtil family ("GB", "hours",
+   *     and the binary "MiBy" / "KiBy"), in which case the value is
+   *     converted into that family's base first.
    */
   private static toScalableUnit(
     value: number,

package/Utils/Monitor/PlatformMetricUnitUtil.ts

@@ -0,0 +1,215 @@
+import Dictionary from "../../Types/Dictionary";
+import MonitorType from "../../Types/Monitor/MonitorType";
+import { getCephMetricByMetricName } from "../../Types/Monitor/CephMetricCatalog";
+import { getDockerMetricByMetricName } from "../../Types/Monitor/DockerMetricCatalog";
+import { getDockerSwarmMetricByMetricName } from "../../Types/Monitor/DockerSwarmMetricCatalog";
+import { getHostMetricByMetricName } from "../../Types/Monitor/HostMetricCatalog";
+import { getIoTMetricByMetricName } from "../../Types/Monitor/IotMetricCatalog";
+import { getKubernetesMetricByMetricName } from "../../Types/Monitor/KubernetesMetricCatalog";
+import { getPodmanMetricByMetricName } from "../../Types/Monitor/PodmanMetricCatalog";
+import { getProxmoxMetricByMetricName } from "../../Types/Monitor/ProxmoxMetricCatalog";
+import { getVMwareMetricByMetricName } from "../../Types/Monitor/VMwareMetricCatalog";
+
+/*
+ * The platforms that ship their own metric catalog. Each catalog names the
+ * unit its metrics' stored values are in.
+ */
+export type MetricCatalogPlatform =
+  | "kubernetes"
+  | "proxmox"
+  | "vmware"
+  | "dockerSwarm"
+  | "ceph"
+  | "docker"
+  | "podman"
+  | "host"
+  | "iot";
+
+/*
+ * What unit a platform monitor's metric values are in.
+ *
+ * Two sources can answer that, and they disagree often enough to matter:
+ *
+ *  - the unit the OpenTelemetry exporter DECLARED, stored on MetricType
+ *    (k8s.node.allocatable_memory → "By");
+ *  - the unit the platform's metric catalog SAYS the values are in
+ *    (KubernetesMetricCatalog, DockerMetricCatalog, ...).
+ *
+ * The catalog wins. It was written against what each agent actually sends,
+ * and the exporters are not always right about their own numbers:
+ * docker_stats declares container.cpu.utilization and
+ * container.memory.percent with the unit "1" but sends 0–100. Taking the
+ * declared "1" would render 85.3 as "8530.00%", and — worse — a threshold
+ * typed in "%" would convert every sample ×100 and fire forever. kubeletstats
+ * declares k8s.node.cpu.utilization as "1" but it is a cores gauge.
+ *
+ * The declared unit is the fallback for everything the catalog does not
+ * know, which is how k8s.node.allocatable_memory reads "258 GB" instead of
+ * "257760964608" even before it has a catalog entry.
+ */
+export default class PlatformMetricUnitUtil {
+  /**
+   * The catalog platform a monitor type reads its metrics from, or null for
+   * monitor types without one (generic Metrics monitors keep the exporter's
+   * declared unit).
+   */
+  public static getPlatformForMonitorType(
+    monitorType: MonitorType | undefined,
+  ): MetricCatalogPlatform | null {
+    switch (monitorType) {
+      case MonitorType.Kubernetes:
+        return "kubernetes";
+      case MonitorType.Proxmox:
+        return "proxmox";
+      case MonitorType.VMware:
+        return "vmware";
+      case MonitorType.DockerSwarm:
+        return "dockerSwarm";
+      case MonitorType.Ceph:
+        return "ceph";
+      case MonitorType.Docker:
+        return "docker";
+      case MonitorType.Podman:
+        return "podman";
+      case MonitorType.Host:
+        return "host";
+      case MonitorType.IoTDevice:
+        return "iot";
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * The unit the platform's catalog declares for a metric, exactly as the
+   * catalog spells it ("bytes", "cores", "ratio", "count", "%"), or
+   * undefined when the catalog does not know the metric or gives it no
+   * unit.
+   */
+  public static getCatalogUnit(input: {
+    platform: MetricCatalogPlatform;
+    metricName: string;
+  }): string | undefined {
+    const unit: string | undefined = PlatformMetricUnitUtil.lookupCatalogUnit(
+      input.platform,
+      input.metricName,
+    );
+
+    return unit && unit.trim() ? unit.trim() : undefined;
+  }
+
+  /**
+   * The unit a platform metric's values are in, spelled so the rest of the
+   * pipeline can convert it: the catalog unit when the catalog has a real
+   * one, else the exporter-declared unit, else undefined.
+   *
+   * The catalogs spell two dimensionless concepts in English. "ratio" (and
+   * "fraction") becomes UCUM's "1", which MetricUnitUtil can convert to a
+   * "%" threshold and MetricValueFormatter renders as a percentage.
+   * "count" names no dimension at all, so it defers to the declared unit
+   * ("{restart}", which renders bare the same way) instead of hiding it.
+   */
+  public static getMetricUnit(input: {
+    platform: MetricCatalogPlatform | null;
+    metricName: string;
+    declaredUnit?: string | null | undefined;
+  }): string | undefined {
+    const catalogUnit: string | undefined = input.platform
+      ? PlatformMetricUnitUtil.toConvertibleUnit(
+          PlatformMetricUnitUtil.getCatalogUnit({
+            platform: input.platform,
+            metricName: input.metricName,
+          }),
+        )
+      : undefined;
+
+    if (catalogUnit) {
+      return catalogUnit;
+    }
+
+    const declaredUnit: string = (input.declaredUnit || "").trim();
+
+    return declaredUnit || undefined;
+  }
+
+  /**
+   * The unit map a platform monitor hands the criteria evaluator: one entry
+   * per metric name, keyed lowercased like MetricMonitorResponse's
+   * `nativeUnitsByMetricName`, holding getMetricUnit's answer. Metrics with
+   * no known unit are left out rather than mapped to "".
+   */
+  public static buildUnitsByMetricName(input: {
+    platform: MetricCatalogPlatform | null;
+    metricNames: Array<string>;
+    declaredUnitsByMetricName: Map<string, string>;
+  }): Dictionary<string> {
+    const unitsByMetricName: Dictionary<string> = {};
+
+    for (const metricName of input.metricNames) {
+      if (!metricName) {
+        continue;
+      }
+
+      const unit: string | undefined = PlatformMetricUnitUtil.getMetricUnit({
+        platform: input.platform,
+        metricName: metricName,
+        declaredUnit: input.declaredUnitsByMetricName.get(
+          metricName.toLowerCase(),
+        ),
+      });
+
+      if (unit) {
+        unitsByMetricName[metricName.toLowerCase()] = unit;
+      }
+    }
+
+    return unitsByMetricName;
+  }
+
+  private static toConvertibleUnit(
+    unit: string | undefined,
+  ): string | undefined {
+    if (!unit) {
+      return undefined;
+    }
+
+    switch (unit.toLowerCase()) {
+      case "ratio":
+      case "fraction":
+        return "1";
+      case "count":
+      case "counts":
+        return undefined;
+      default:
+        return unit;
+    }
+  }
+
+  private static lookupCatalogUnit(
+    platform: MetricCatalogPlatform,
+    metricName: string,
+  ): string | undefined {
+    switch (platform) {
+      case "kubernetes":
+        return getKubernetesMetricByMetricName(metricName)?.unit;
+      case "proxmox":
+        return getProxmoxMetricByMetricName(metricName)?.unit;
+      case "vmware":
+        return getVMwareMetricByMetricName(metricName)?.unit;
+      case "dockerSwarm":
+        return getDockerSwarmMetricByMetricName(metricName)?.unit;
+      case "ceph":
+        return getCephMetricByMetricName(metricName)?.unit;
+      case "docker":
+        return getDockerMetricByMetricName(metricName)?.unit;
+      case "podman":
+        return getPodmanMetricByMetricName(metricName)?.unit;
+      case "host":
+        return getHostMetricByMetricName(metricName)?.unit;
+      case "iot":
+        return getIoTMetricByMetricName(metricName)?.unit;
+      default:
+        return undefined;
+    }
+  }
+}