@oneuptime/common 14.0.2 → 14.0.5

package/Tests/Utils/MetricUnitUtil.test.ts

@@ -288,8 +288,11 @@ describe("MetricUnitUtil", () => {
       expect(MetricUnitUtil.getFamilyBaseUnit("   ")).toBeNull();
       expect(MetricUnitUtil.getFamilyBaseUnit("cores")).toBeNull();
       expect(MetricUnitUtil.getFamilyBaseUnit("widgets")).toBeNull();
-      // Binary prefixes are deliberately not in any family here.
-      expect(MetricUnitUtil.getFamilyBaseUnit("KiBy")).toBeNull();
+      /*
+       * A braced annotation is not a unit, even when the text inside it
+       * is one — MetricValueFormatter unwraps "{KiBy/s}" itself.
+       */
+      expect(MetricUnitUtil.getFamilyBaseUnit("{KiBy}")).toBeNull();
     });
 
     /*
@@ -316,6 +319,228 @@ describe("MetricUnitUtil", () => {
     });
   });
 
+  /*
+   * Binary (IEC) byte units — powers of 1024. The vcenter receiver reports
+   * memory in "MiBy" and "KiBy", and before these were family members a
+   * "MiBy" sample could not be converted at all: a 2 GB threshold on a
+   * MiBy metric was compared as "2 MiB", and the notification formatter
+   * printed "1048576 MiB" because the unit had no base to scale from.
+   */
+  describe("binary (IEC) byte units", () => {
+    const binaryUnits: Array<{ spellings: Array<string>; bytes: number }> = [
+      {
+        spellings: ["KiBy", "KiB", "kib", "kiby", "kibibyte", "kibibytes"],
+        bytes: 1024,
+      },
+      {
+        spellings: ["MiBy", "MiB", "mib", "miby", "mebibyte", "mebibytes"],
+        bytes: 1024 ** 2,
+      },
+      {
+        spellings: ["GiBy", "GiB", "gib", "giby", "gibibyte", "gibibytes"],
+        bytes: 1024 ** 3,
+      },
+      {
+        spellings: ["TiBy", "TiB", "tib", "tiby", "tebibyte", "tebibytes"],
+        bytes: 1024 ** 4,
+      },
+      {
+        spellings: ["PiBy", "PiB", "pib", "piby", "pebibyte", "pebibytes"],
+        bytes: 1024 ** 5,
+      },
+    ];
+
+    test("every spelling belongs to the byte family", () => {
+      for (const { spellings } of binaryUnits) {
+        for (const unit of spellings) {
+          expect(MetricUnitUtil.getFamilyBaseUnit(unit)).toBe("B");
+        }
+      }
+    });
+
+    test("every spelling converts to its power of 1024 in bytes", () => {
+      for (const { spellings, bytes } of binaryUnits) {
+        for (const unit of spellings) {
+          expect(
+            MetricUnitUtil.convertToMetricUnit({
+              value: 1,
+              fromUnit: unit,
+              metricUnit: "By",
+            }),
+          ).toBe(bytes);
+        }
+      }
+    });
+
+    test("is case- and whitespace-insensitive", () => {
+      expect(MetricUnitUtil.getFamilyBaseUnit("  MIBY  ")).toBe("B");
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 3,
+          fromUnit: "GIB",
+          metricUnit: " bytes ",
+        }),
+      ).toBe(3 * 1024 ** 3);
+    });
+
+    test("a MiBy value converts into a GB threshold (was returned unchanged)", () => {
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 2048,
+          fromUnit: "MiBy",
+          metricUnit: "GB",
+        }),
+      ).toBe(2.147483648);
+    });
+
+    test("a GB threshold converts into a MiBy metric's unit", () => {
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 2,
+          fromUnit: "GB",
+          metricUnit: "MiBy",
+        }),
+      ).toBe(1907.3486328125);
+    });
+
+    test("converts between binary units by powers of 1024", () => {
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 1,
+          fromUnit: "GiBy",
+          metricUnit: "MiBy",
+        }),
+      ).toBe(1024);
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 1048576,
+          fromUnit: "KiBy",
+          metricUnit: "GiBy",
+        }),
+      ).toBe(1);
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 1,
+          fromUnit: "PiB",
+          metricUnit: "TiB",
+        }),
+      ).toBe(1024);
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 1048576,
+          fromUnit: "bytes",
+          metricUnit: "KiBy",
+        }),
+      ).toBe(1024);
+    });
+
+    test("the UCUM and short spellings of one unit are the same unit", () => {
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 512,
+          fromUnit: "MiB",
+          metricUnit: "MiBy",
+        }),
+      ).toBe(512);
+    });
+
+    test("still refuses to convert across families", () => {
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 100,
+          fromUnit: "MiBy",
+          metricUnit: "sec",
+        }),
+      ).toBe(100);
+      expect(
+        MetricUnitUtil.convertToMetricUnit({
+          value: 100,
+          fromUnit: "KiBy",
+          metricUnit: "kbit",
+        }),
+      ).toBe(100);
+    });
+
+    /*
+     * The binary units are CONVERSION-ONLY. The threshold and legend unit
+     * pickers (CriteriaFilter, MetricAlias) are built from
+     * getCompatibleUnits / getCanonicalUnitValue / hasCompatibleUnitFamily,
+     * and every bytes dropdown would otherwise grow five near-duplicates
+     * of the six decimal units. So the picker contract is exactly what it
+     * was before the binary units existed.
+     */
+    describe("never reach the unit pickers", () => {
+      test("no bytes dropdown offers a binary unit", () => {
+        for (const unit of ["B", "By", "bytes", "KB", "MB", "GB", "TB"]) {
+          expect(
+            MetricUnitUtil.getCompatibleUnits(unit).map(
+              (o: { value: string; label: string }) => {
+                return o.value;
+              },
+            ),
+          ).toEqual(["B", "KB", "MB", "GB", "TB", "PB"]);
+        }
+      });
+
+      test("a binary native unit still gets its raw spelling as the only option", () => {
+        for (const { spellings } of binaryUnits) {
+          for (const unit of spellings) {
+            expect(MetricUnitUtil.getCompatibleUnits(unit)).toEqual([
+              { value: unit, label: unit },
+            ]);
+            expect(MetricUnitUtil.getCanonicalUnitValue(unit)).toBe(unit);
+            expect(MetricUnitUtil.hasCompatibleUnitFamily(unit)).toBe(false);
+          }
+        }
+      });
+    });
+  });
+
+  /*
+   * The binary units were added to the SAME family as B / KB / MB. Every
+   * decimal answer below is pinned so that addition can never shift one.
+   */
+  describe("decimal bytes are unchanged by the binary units", () => {
+    test("each decimal spelling still converts by powers of 1000", () => {
+      const cases: Array<[string, number]> = [
+        ["B", 1],
+        ["b", 1],
+        ["By", 1],
+        ["byte", 1],
+        ["bytes", 1],
+        ["KB", 1e3],
+        ["kby", 1e3],
+        ["kilobytes", 1e3],
+        ["MB", 1e6],
+        ["mby", 1e6],
+        ["GB", 1e9],
+        ["gby", 1e9],
+        ["TB", 1e12],
+        ["PB", 1e15],
+      ];
+
+      for (const [unit, bytes] of cases) {
+        expect(
+          MetricUnitUtil.convertToMetricUnit({
+            value: 1,
+            fromUnit: unit,
+            metricUnit: "B",
+          }),
+        ).toBe(bytes);
+        expect(MetricUnitUtil.getFamilyBaseUnit(unit)).toBe("B");
+      }
+    });
+
+    test("each decimal spelling still canonicalizes to its decimal unit", () => {
+      expect(MetricUnitUtil.getCanonicalUnitValue("By")).toBe("B");
+      expect(MetricUnitUtil.getCanonicalUnitValue("bytes")).toBe("B");
+      expect(MetricUnitUtil.getCanonicalUnitValue("kby")).toBe("KB");
+      expect(MetricUnitUtil.getCanonicalUnitValue("GB")).toBe("GB");
+      expect(MetricUnitUtil.hasCompatibleUnitFamily("By")).toBe(true);
+      expect(MetricUnitUtil.hasCompatibleUnitFamily("KB")).toBe(true);
+    });
+  });
+
   describe("hasCompatibleUnitFamily", () => {
     test("true for known families", () => {
       expect(MetricUnitUtil.hasCompatibleUnitFamily("bytes")).toBe(true);

package/Tests/Utils/Monitor/MetricValueFormatter.test.ts

@@ -1,5 +1,9 @@
 import MetricValueFormatter from "../../../Utils/Monitor/MetricValueFormatter";
 import ValueFormatter from "../../../Utils/ValueFormatter";
+import {
+  VMwareMetricDefinition,
+  getAllVMwareMetrics,
+} from "../../../Types/Monitor/VMwareMetricCatalog";
 import { describe, expect, test } from "@jest/globals";
 
 /*
@@ -115,6 +119,255 @@ describe("MetricValueFormatter", () => {
     });
   });
 
+  /*
+   * The vcenter receiver reports memory in OTel's binary byte units
+   * ("MiBy", "KiBy"). MetricUnitUtil had no family for them, so they fell
+   * through to the no-ladder branch: a host with 1 TiB of memory in use
+   * reached the inbox as "1048576 MiB". They now go through the same
+   * decimal ladder as every other byte value, via their size in bytes.
+   */
+  describe("format — binary (IEC) byte units", () => {
+    test("scale through the bytes ladder", () => {
+      expect(MetricValueFormatter.format({ value: 2048, unit: "MiBy" })).toBe(
+        "2.15 GB",
+      );
+      expect(
+        MetricValueFormatter.format({ value: 1048576, unit: "MiBy" }),
+      ).toBe("1.1 TB");
+      expect(MetricValueFormatter.format({ value: 1024, unit: "KiBy" })).toBe(
+        "1.05 MB",
+      );
+      expect(MetricValueFormatter.format({ value: 1, unit: "KiBy" })).toBe(
+        "1.02 KB",
+      );
+      expect(MetricValueFormatter.format({ value: 3, unit: "GiBy" })).toBe(
+        "3.22 GB",
+      );
+      expect(MetricValueFormatter.format({ value: 1.5, unit: "TiBy" })).toBe(
+        "1.65 TB",
+      );
+      expect(MetricValueFormatter.format({ value: 2, unit: "PiBy" })).toBe(
+        "2.25 PB",
+      );
+    });
+
+    test("read exactly as the same number of bytes would", () => {
+      const cases: Array<[number, string, number]> = [
+        [2048, "MiBy", 1024 ** 2],
+        [123456789, "MiBy", 1024 ** 2],
+        [700, "KiBy", 1024],
+        [0.5, "GiBy", 1024 ** 3],
+        [3, "TiBy", 1024 ** 4],
+      ];
+
+      for (const [value, unit, bytesPerUnit] of cases) {
+        expect(MetricValueFormatter.format({ value: value, unit: unit })).toBe(
+          MetricValueFormatter.format({
+            value: value * bytesPerUnit,
+            unit: "By",
+          }),
+        );
+      }
+    });
+
+    test("accept the short and spelled-out IEC names too", () => {
+      expect(MetricValueFormatter.format({ value: 2048, unit: "MiB" })).toBe(
+        "2.15 GB",
+      );
+      expect(
+        MetricValueFormatter.format({ value: 2048, unit: "mebibytes" }),
+      ).toBe("2.15 GB");
+      expect(MetricValueFormatter.format({ value: 2048, unit: "miby" })).toBe(
+        "2.15 GB",
+      );
+    });
+
+    test("keep the sign, and read zero in bytes like any other byte unit", () => {
+      expect(MetricValueFormatter.format({ value: -2048, unit: "MiBy" })).toBe(
+        "-2.15 GB",
+      );
+      expect(MetricValueFormatter.format({ value: 0, unit: "MiBy" })).toBe(
+        "0 B",
+      );
+      // The decimal prefixes have always done the same.
+      expect(MetricValueFormatter.format({ value: 0, unit: "GB" })).toBe("0 B");
+    });
+
+    test("scale as the numerator of a rate", () => {
+      expect(MetricValueFormatter.format({ value: 2500, unit: "KiBy/s" })).toBe(
+        "2.56 MB/s",
+      );
+      expect(MetricValueFormatter.format({ value: 100, unit: "MiBy/s" })).toBe(
+        "105 MB/s",
+      );
+    });
+
+    test("are displayable and spelled out by name", () => {
+      expect(MetricValueFormatter.hasDisplayableUnit("MiBy")).toBe(true);
+      expect(MetricValueFormatter.hasDisplayableUnit("KiBy")).toBe(true);
+      expect(MetricValueFormatter.getReadableUnit("MiBy")).toBe("Mebibytes");
+      expect(MetricValueFormatter.getReadableUnit("KiBy")).toBe("Kibibytes");
+    });
+  });
+
+  /*
+   * vcenter declares its disk and network throughput as "{KiBy/s}" —
+   * UCUM annotation braces around a unit that is perfectly real. The
+   * annotation rule hid it, so about 2.56 GB/s of disk traffic reached the
+   * inbox as the bare "2500000". Braces are now unwrapped when, and only
+   * when, what they hold is a unit the formatter can scale.
+   */
+  describe("format — braced units that hold a real unit", () => {
+    test("a braced byte rate is unwrapped and scaled", () => {
+      expect(
+        MetricValueFormatter.format({ value: 2500000, unit: "{KiBy/s}" }),
+      ).toBe("2.56 GB/s");
+      expect(
+        MetricValueFormatter.format({ value: 1500000, unit: "{By/s}" }),
+      ).toBe("1.5 MB/s");
+      expect(
+        MetricValueFormatter.format({ value: 512, unit: "{KiBy/s}" }),
+      ).toBe("524 KB/s");
+    });
+
+    test("renders exactly as the unbraced unit does", () => {
+      for (const [value, unit] of [
+        [2500000, "KiBy/s"],
+        [1500000, "By/s"],
+        [2048, "MiBy"],
+        [1500, "ms"],
+      ] as Array<[number, string]>) {
+        expect(
+          MetricValueFormatter.format({ value: value, unit: `{${unit}}` }),
+        ).toBe(MetricValueFormatter.format({ value: value, unit: unit }));
+      }
+    });
+
+    test("tolerates whitespace inside and around the braces", () => {
+      expect(
+        MetricValueFormatter.format({ value: 2500000, unit: " { KiBy/s } " }),
+      ).toBe("2.56 GB/s");
+    });
+
+    test("a braced COUNT is still hidden, rate or not", () => {
+      for (const unit of [
+        "{errors/s}",
+        "{packets/s}",
+        "{operations/s}",
+        "{congestions/s}",
+        "{restarts}",
+        "{cpu}",
+        "{shares}",
+        "{count}",
+        "{1}",
+        "{%}",
+        "{}",
+      ]) {
+        expect(MetricValueFormatter.format({ value: 1500, unit: unit })).toBe(
+          "1500",
+        );
+        expect(MetricValueFormatter.hasDisplayableUnit(unit)).toBe(false);
+        expect(MetricValueFormatter.getReadableUnit(unit)).toBeNull();
+      }
+    });
+
+    test("hasDisplayableUnit and getReadableUnit agree with format", () => {
+      expect(MetricValueFormatter.hasDisplayableUnit("{KiBy/s}")).toBe(true);
+      expect(MetricValueFormatter.hasDisplayableUnit("{By/s}")).toBe(true);
+      expect(MetricValueFormatter.getReadableUnit("{KiBy/s}")).toBe(
+        "Kibibytes per Second",
+      );
+      expect(MetricValueFormatter.getReadableUnit("{By/s}")).toBe(
+        "Bytes per Second",
+      );
+    });
+  });
+
+  /*
+   * The binary byte units joined the SAME MetricUnitUtil family as the
+   * decimal ones. Nothing about a decimal byte value may have moved.
+   */
+  describe("format — decimal bytes are unchanged", () => {
+    test("every decimal byte spelling still renders what the dashboard does", () => {
+      for (const [value, unit] of [
+        [0, "B"],
+        [999, "By"],
+        [1000, "bytes"],
+        [257760964608, "By"],
+        [1073741824, "bytes"],
+        [1500000, "By/s"],
+      ] as Array<[number, string]>) {
+        expect(MetricValueFormatter.format({ value: value, unit: unit })).toBe(
+          ValueFormatter.formatValue(value, unit),
+        );
+      }
+    });
+
+    test("decimal prefixes still convert by powers of 1000", () => {
+      expect(MetricValueFormatter.format({ value: 2048, unit: "MB" })).toBe(
+        "2.05 GB",
+      );
+      expect(MetricValueFormatter.format({ value: 1500, unit: "KB" })).toBe(
+        "1.5 MB",
+      );
+      expect(MetricValueFormatter.format({ value: 257.76, unit: "GB" })).toBe(
+        "258 GB",
+      );
+    });
+  });
+
+  /*
+   * Every VMware memory and throughput metric is declared in a binary unit
+   * or a braced byte rate. Enumerated, so a catalog entry added later in
+   * either shape is covered without anyone remembering to add it here.
+   */
+  describe("format — every VMware byte metric reads as a size", () => {
+    const binaryByteUnit: RegExp = /^[KMGTP]iBy$/;
+    const bracedByteRate: RegExp = /^\{[KMGTP]?i?By\/s\}$/;
+    const bareNumber: RegExp = /^-?\d+(\.\d+)?$/;
+    const scaledSize: RegExp = /^\d+(\.\d+)? (B|KB|MB|GB|TB|PB)(\/s)?$/;
+
+    const byteMetrics: Array<VMwareMetricDefinition> =
+      getAllVMwareMetrics().filter((m: VMwareMetricDefinition) => {
+        return (
+          binaryByteUnit.test(m.unit || "") || bracedByteRate.test(m.unit || "")
+        );
+      });
+
+    test("the catalog still has metrics in both shapes (guards the guard)", () => {
+      expect(
+        byteMetrics.some((m: VMwareMetricDefinition) => {
+          return binaryByteUnit.test(m.unit || "");
+        }),
+      ).toBe(true);
+      expect(
+        byteMetrics.some((m: VMwareMetricDefinition) => {
+          return bracedByteRate.test(m.unit || "");
+        }),
+      ).toBe(true);
+    });
+
+    test.each(
+      byteMetrics.map((m: VMwareMetricDefinition) => {
+        return [m.metricName, m.unit as string];
+      }),
+    )(
+      "%s (%s) never renders as bare digits",
+      (metricName: string, unit: string) => {
+        const formatted: string = MetricValueFormatter.format({
+          value: 123456789,
+          unit: unit,
+          metricName: metricName,
+        });
+
+        expect(formatted).not.toMatch(bareNumber);
+        expect(formatted).toMatch(scaledSize);
+        // A rate stays a rate; a size stays a size.
+        expect(formatted.endsWith("/s")).toBe(unit.endsWith("/s}"));
+      },
+    );
+  });
+
   describe("format — percent and fraction metrics", () => {
     test("percent units render inline with two decimals", () => {
       expect(MetricValueFormatter.format({ value: 87.5, unit: "%" })).toBe(
@@ -174,6 +427,35 @@ describe("MetricValueFormatter", () => {
       ).toBe("0.18");
     });
 
+    /*
+     * A monitor built from the Redis chart ("Create monitor") or in the
+     * Metrics explorer carries the receiver's native "1" (or the catalog's
+     * "ratio"), not the recommended template's legend unit. Its alert must
+     * still read 1.62 against a threshold of 1.5, never 162% against 150%.
+     */
+    test("Redis' memory fragmentation ratio is the ratio, not a percentage", () => {
+      expect(
+        MetricValueFormatter.format({
+          value: 1.62,
+          unit: "1",
+          metricName: "redis.memory.fragmentation_ratio",
+        }),
+      ).toBe("1.62");
+      expect(
+        MetricValueFormatter.format({
+          value: 1.5,
+          unit: "ratio",
+          metricName: "redis.memory.fragmentation_ratio",
+        }),
+      ).toBe("1.5");
+      expect(
+        MetricValueFormatter.hasDisplayableUnit(
+          "1",
+          "redis.memory.fragmentation_ratio",
+        ),
+      ).toBe(false);
+    });
+
     test("a fraction unit with no metric name stays a bare number", () => {
       expect(MetricValueFormatter.format({ value: 0.25, unit: "1" })).toBe(
         "0.25",
@@ -229,8 +511,12 @@ describe("MetricValueFormatter", () => {
       expect(MetricValueFormatter.format({ value: 1500, unit: "kbit" })).toBe(
         "1500 kbit",
       );
-      expect(MetricValueFormatter.format({ value: 1024, unit: "KiBy" })).toBe(
-        "1024 KiB",
+      /*
+       * "KiBy" used to be the example here ("1024 KiB"). It has a ladder
+       * now — see "format — binary (IEC) byte units" below.
+       */
+      expect(MetricValueFormatter.format({ value: 2400, unit: "MHz" })).toBe(
+        "2400 MHz",
       );
       expect(MetricValueFormatter.format({ value: 4200, unit: "ops" })).toBe(
         "4200 ops",