@oneuptime/common 11.6.0 → 11.6.2

package/Tests/Utils/Traces/CriticalPath.test.ts

@@ -0,0 +1,178 @@
+import CriticalPathUtil, {
+  CriticalPathResult,
+  ServiceBreakdown,
+  SpanData,
+  SpanSelfTime,
+} from "../../../Utils/Traces/CriticalPath";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * CriticalPathUtil is a zero-dependency interval/graph engine over trace spans.
+ * The math is subtle (overlapping-child interval merge, longest-weighted path
+ * with self-time), and its output drives the "where did the latency go" views,
+ * so these tests pin the numeric behavior with hand-computed fixtures.
+ */
+
+function span(
+  spanId: string,
+  parentSpanId: string | undefined,
+  start: number,
+  end: number,
+  primaryEntityId?: string,
+): SpanData {
+  return {
+    spanId,
+    parentSpanId,
+    startTimeUnixNano: start,
+    endTimeUnixNano: end,
+    durationUnixNano: end - start,
+    primaryEntityId,
+    name: spanId,
+  };
+}
+
+describe("CriticalPathUtil.computeSelfTimes", () => {
+  test("a leaf span's self-time equals its whole duration", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("a", undefined, 0, 100),
+    ]);
+
+    const a: SpanSelfTime = times.get("a")!;
+    expect(a.selfTimeUnixNano).toBe(100);
+    expect(a.childTimeUnixNano).toBe(0);
+    expect(a.selfTimePercent).toBe(100);
+  });
+
+  test("subtracts a single child's covered time", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("root", undefined, 0, 100),
+      span("child", "root", 10, 40),
+    ]);
+
+    expect(times.get("root")!.selfTimeUnixNano).toBe(70);
+    expect(times.get("root")!.childTimeUnixNano).toBe(30);
+    expect(times.get("root")!.selfTimePercent).toBe(70);
+  });
+
+  test("sums two non-overlapping children", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("root", undefined, 0, 100),
+      span("c1", "root", 10, 30),
+      span("c2", "root", 50, 80),
+    ]);
+    // covered = 20 + 30 = 50 -> self = 50
+    expect(times.get("root")!.childTimeUnixNano).toBe(50);
+    expect(times.get("root")!.selfTimeUnixNano).toBe(50);
+  });
+
+  test("merges overlapping children into one interval", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("root", undefined, 0, 100),
+      span("c1", "root", 10, 50),
+      span("c2", "root", 30, 70),
+    ]);
+    // merged interval [10,70] = 60 -> self = 40
+    expect(times.get("root")!.childTimeUnixNano).toBe(60);
+    expect(times.get("root")!.selfTimeUnixNano).toBe(40);
+  });
+
+  test("clamps children that spill past the parent window", () => {
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      span("root", undefined, 0, 100),
+      span("c1", "root", -50, 150),
+    ]);
+    // clamped to [0,100] = 100 -> self = 0
+    expect(times.get("root")!.childTimeUnixNano).toBe(100);
+    expect(times.get("root")!.selfTimeUnixNano).toBe(0);
+  });
+
+  test("self-time is floored at zero and percent is zero for a zero-duration span", () => {
+    const zero: SpanData = span("z", undefined, 5, 5);
+    const times: Map<string, SpanSelfTime> = CriticalPathUtil.computeSelfTimes([
+      zero,
+    ]);
+    expect(times.get("z")!.selfTimeUnixNano).toBe(0);
+    expect(times.get("z")!.selfTimePercent).toBe(0);
+  });
+});
+
+describe("CriticalPathUtil.computeCriticalPath", () => {
+  test("returns all-zero result for an empty trace", () => {
+    const result: CriticalPathResult = CriticalPathUtil.computeCriticalPath([]);
+    expect(result).toEqual({
+      criticalPathSpanIds: [],
+      totalTraceDurationUnixNano: 0,
+      criticalPathDurationUnixNano: 0,
+    });
+  });
+
+  test("a single span is its own critical path", () => {
+    const result: CriticalPathResult = CriticalPathUtil.computeCriticalPath([
+      span("only", undefined, 0, 100),
+    ]);
+    expect(result.criticalPathSpanIds).toEqual(["only"]);
+    expect(result.totalTraceDurationUnixNano).toBe(100);
+    expect(result.criticalPathDurationUnixNano).toBe(100);
+  });
+
+  test("follows the heavier of two parallel children", () => {
+    const result: CriticalPathResult = CriticalPathUtil.computeCriticalPath([
+      span("root", undefined, 0, 100),
+      span("fast", "root", 10, 40), // duration 30
+      span("slow", "root", 10, 90), // duration 80
+    ]);
+
+    expect(result.criticalPathSpanIds).toEqual(["root", "slow"]);
+    expect(result.totalTraceDurationUnixNano).toBe(100);
+    // root self-time (100 - merged[10,90]=80 => 20) + slow weight 80 = 100
+    expect(result.criticalPathDurationUnixNano).toBe(100);
+  });
+
+  test("treats a span whose parent is absent from the set as a root", () => {
+    const result: CriticalPathResult = CriticalPathUtil.computeCriticalPath([
+      span("orphan", "missing-parent", 0, 50),
+    ]);
+    expect(result.criticalPathSpanIds).toEqual(["orphan"]);
+    expect(result.criticalPathDurationUnixNano).toBe(50);
+  });
+});
+
+describe("CriticalPathUtil.computeServiceBreakdown", () => {
+  test("aggregates self-time per service and sorts descending", () => {
+    const breakdown: Array<ServiceBreakdown> =
+      CriticalPathUtil.computeServiceBreakdown([
+        span("root", undefined, 0, 100, "A"),
+        span("child", "root", 20, 60, "B"),
+      ]);
+
+    // root self = 100 - 40 = 60 (service A); child self = 40 (service B)
+    expect(breakdown).toHaveLength(2);
+    expect(breakdown[0]!.primaryEntityId).toBe("A");
+    expect(breakdown[0]!.selfTimeUnixNano).toBe(60);
+    expect(breakdown[0]!.percentOfTrace).toBe(60);
+    expect(breakdown[1]!.primaryEntityId).toBe("B");
+    expect(breakdown[1]!.selfTimeUnixNano).toBe(40);
+    expect(breakdown[1]!.percentOfTrace).toBe(40);
+  });
+
+  test("groups spans without a service id under 'unknown'", () => {
+    const breakdown: Array<ServiceBreakdown> =
+      CriticalPathUtil.computeServiceBreakdown([span("a", undefined, 0, 10)]);
+
+    expect(breakdown).toHaveLength(1);
+    expect(breakdown[0]!.primaryEntityId).toBe("unknown");
+    expect(breakdown[0]!.spanCount).toBe(1);
+  });
+
+  test("accumulates span counts and durations per service", () => {
+    const breakdown: Array<ServiceBreakdown> =
+      CriticalPathUtil.computeServiceBreakdown([
+        span("s1", undefined, 0, 100, "A"),
+        span("s2", undefined, 100, 150, "A"),
+      ]);
+
+    expect(breakdown).toHaveLength(1);
+    expect(breakdown[0]!.spanCount).toBe(2);
+    expect(breakdown[0]!.totalDurationUnixNano).toBe(150);
+  });
+});

package/Tests/Utils/ValueFormatter.test.ts

@@ -0,0 +1,305 @@
+import ValueFormatter from "../../Utils/ValueFormatter";
+
+describe("ValueFormatter", () => {
+  describe("formatValue - bytes", () => {
+    test("scales bytes up to the right unit", () => {
+      expect(ValueFormatter.formatValue(1048576, "bytes")).toBe("1.05 MB");
+      expect(ValueFormatter.formatValue(1e6, "bytes")).toBe("1 MB");
+      expect(ValueFormatter.formatValue(1e9, "bytes")).toBe("1 GB");
+      expect(ValueFormatter.formatValue(1e12, "bytes")).toBe("1 TB");
+      expect(ValueFormatter.formatValue(1e15, "bytes")).toBe("1 PB");
+    });
+
+    test("keeps small byte values in B", () => {
+      expect(ValueFormatter.formatValue(512, "bytes")).toBe("512 B");
+      expect(ValueFormatter.formatValue(1, "bytes")).toBe("1 B");
+    });
+
+    test("recognizes UCUM byte aliases", () => {
+      expect(ValueFormatter.formatValue(2000, "By")).toBe("2 KB");
+      expect(ValueFormatter.formatValue(2000, "b")).toBe("2 KB");
+      expect(ValueFormatter.formatValue(2000, "byte")).toBe("2 KB");
+    });
+
+    test("renders 0 bytes with the natural byte unit", () => {
+      expect(ValueFormatter.formatValue(0, "bytes")).toBe("0 B");
+    });
+
+    test("handles negative byte values", () => {
+      expect(ValueFormatter.formatValue(-2000, "bytes")).toBe("-2 KB");
+    });
+  });
+
+  describe("formatValue - seconds", () => {
+    test("scales seconds into larger units", () => {
+      expect(ValueFormatter.formatValue(60, "seconds")).toBe("1 min");
+      expect(ValueFormatter.formatValue(3600, "seconds")).toBe("1 hours");
+      expect(ValueFormatter.formatValue(86400, "seconds")).toBe("1 days");
+    });
+
+    test("scales sub-second values down", () => {
+      expect(ValueFormatter.formatValue(0.5, "seconds")).toBe("500 ms");
+      expect(ValueFormatter.formatValue(0.0005, "seconds")).toBe("500 µs");
+    });
+
+    test("renders 0 seconds with the natural second unit, not ns", () => {
+      expect(ValueFormatter.formatValue(0, "seconds")).toBe("0 sec");
+    });
+
+    test("recognizes second aliases", () => {
+      expect(ValueFormatter.formatValue(120, "s")).toBe("2 min");
+      expect(ValueFormatter.formatValue(120, "sec")).toBe("2 min");
+    });
+  });
+
+  describe("formatValue - milliseconds", () => {
+    test("scales milliseconds into seconds and beyond", () => {
+      expect(ValueFormatter.formatValue(1000, "ms")).toBe("1 sec");
+      expect(ValueFormatter.formatValue(60000, "ms")).toBe("1 min");
+    });
+
+    test("keeps small ms values", () => {
+      expect(ValueFormatter.formatValue(5, "ms")).toBe("5 ms");
+    });
+
+    test("renders 0 ms with the natural ms unit", () => {
+      expect(ValueFormatter.formatValue(0, "ms")).toBe("0 ms");
+    });
+  });
+
+  describe("formatValue - percent", () => {
+    test("renders percent inline with two decimals", () => {
+      expect(ValueFormatter.formatValue(42, "%")).toBe("42.00%");
+      expect(ValueFormatter.formatValue(100, "%")).toBe("100.00%");
+      expect(ValueFormatter.formatValue(2.04, "%")).toBe("2.04%");
+    });
+
+    test("treats spelled-out percent variants the same", () => {
+      expect(ValueFormatter.formatValue(50, "percent")).toBe("50.00%");
+      expect(ValueFormatter.formatValue(50, "percentage")).toBe("50.00%");
+      expect(ValueFormatter.formatValue(50, "pct")).toBe("50.00%");
+    });
+
+    test("non-finite percent falls back to 0.00", () => {
+      expect(ValueFormatter.formatValue(Infinity, "%")).toBe("0.00%");
+      expect(ValueFormatter.formatValue(NaN, "%")).toBe("0.00%");
+    });
+  });
+
+  describe("formatValue - dimensionless and fraction metrics", () => {
+    test("dimensionless unit '1' renders a bare number", () => {
+      expect(ValueFormatter.formatValue(1234, "1")).toBe("1.23K");
+      expect(ValueFormatter.formatValue(5, "1")).toBe("5");
+    });
+
+    test("empty unit renders a bare number", () => {
+      expect(ValueFormatter.formatValue(5, "")).toBe("5");
+    });
+
+    test("fraction metric with unit '1' renders as a percentage", () => {
+      expect(
+        ValueFormatter.formatValue(0.25, "1", {
+          metricName: "system.cpu.utilization",
+        }),
+      ).toBe("25.00%");
+      expect(
+        ValueFormatter.formatValue(0.5, "1", {
+          metricName: "db.client.connection.usage_ratio",
+        }),
+      ).toBe("50.00%");
+    });
+
+    test("non-fraction metric with unit '1' stays a bare number", () => {
+      expect(
+        ValueFormatter.formatValue(0.25, "1", {
+          metricName: "http.server.request.count",
+        }),
+      ).toBe("0.25");
+    });
+  });
+
+  describe("formatValue - annotation-only units", () => {
+    test("renders bare number for UCUM annotation units", () => {
+      expect(ValueFormatter.formatValue(42, "{thread}")).toBe("42");
+      expect(ValueFormatter.formatValue(1500, "{packets}")).toBe("1.5K");
+    });
+  });
+
+  describe("formatValue - compound rate units", () => {
+    test("scales the numerator and keeps a compact denominator", () => {
+      expect(ValueFormatter.formatValue(1500000, "By/s")).toBe("1.5 MB/s");
+      expect(ValueFormatter.formatValue(2000, "bytes/s")).toBe("2 KB/s");
+    });
+
+    test("falls back to readable form for unknown numerator", () => {
+      expect(ValueFormatter.formatValue(5, "requests/s")).toBe(
+        "5 requests per Second",
+      );
+    });
+  });
+
+  describe("formatValue - unknown units", () => {
+    test("formats number and appends a readable unit name", () => {
+      expect(ValueFormatter.formatValue(10, "hz")).toBe("10 Hertz");
+      expect(ValueFormatter.formatValue(5, "v")).toBe("5 Volts");
+    });
+
+    test("keeps the original unit when unrecognized", () => {
+      expect(ValueFormatter.formatValue(5, "widgets")).toBe("5 widgets");
+    });
+  });
+
+  describe("formatValue - large number abbreviation", () => {
+    test("abbreviates thousands, millions, billions", () => {
+      expect(ValueFormatter.formatValue(5000, "widgets")).toBe("5K widgets");
+      expect(ValueFormatter.formatValue(1500000, "widgets")).toBe(
+        "1.5M widgets",
+      );
+      expect(ValueFormatter.formatValue(2000000000, "widgets")).toBe(
+        "2B widgets",
+      );
+    });
+
+    test("trims trailing zeros but keeps distinguishing decimals", () => {
+      expect(ValueFormatter.formatValue(119250000000, "widgets")).toBe(
+        "119.25B widgets",
+      );
+    });
+  });
+
+  describe("formatValue - small number precision", () => {
+    test("keeps two significant digits below 1", () => {
+      expect(ValueFormatter.formatValue(0.004, "widgets")).toBe(
+        "0.004 widgets",
+      );
+      expect(ValueFormatter.formatValue(0.006, "widgets")).toBe(
+        "0.006 widgets",
+      );
+    });
+
+    test("expands very small numbers out of exponential notation", () => {
+      const result: string = ValueFormatter.formatValue(0.00000012, "widgets");
+      // Should not fall back to exponential notation like "1.2e-7".
+      expect(result).not.toMatch(/e[+-]/i);
+      expect(result).toContain("0.00000012");
+    });
+  });
+
+  describe("isPercentUnit", () => {
+    test("returns true for percent variants", () => {
+      expect(ValueFormatter.isPercentUnit("%")).toBe(true);
+      expect(ValueFormatter.isPercentUnit("percent")).toBe(true);
+      expect(ValueFormatter.isPercentUnit("PERCENTAGE")).toBe(true);
+      expect(ValueFormatter.isPercentUnit(" pct ")).toBe(true);
+    });
+
+    test("returns false otherwise", () => {
+      expect(ValueFormatter.isPercentUnit("bytes")).toBe(false);
+      expect(ValueFormatter.isPercentUnit(undefined)).toBe(false);
+      expect(ValueFormatter.isPercentUnit("")).toBe(false);
+    });
+  });
+
+  describe("isFractionMetric", () => {
+    test("matches utilization/ratio/fraction/percent suffixes", () => {
+      expect(ValueFormatter.isFractionMetric("system.cpu.utilization")).toBe(
+        true,
+      );
+      expect(ValueFormatter.isFractionMetric("some_ratio")).toBe(true);
+      expect(ValueFormatter.isFractionMetric("mem.fraction")).toBe(true);
+      expect(ValueFormatter.isFractionMetric("disk_percentage")).toBe(true);
+    });
+
+    test("does not match unrelated names", () => {
+      expect(ValueFormatter.isFractionMetric("request.count")).toBe(false);
+      expect(ValueFormatter.isFractionMetric(undefined)).toBe(false);
+      expect(ValueFormatter.isFractionMetric("")).toBe(false);
+    });
+  });
+
+  describe("isHigherWorseMetric", () => {
+    test("returns false for higher-is-better metrics", () => {
+      expect(
+        ValueFormatter.isHigherWorseMetric("oneuptime.monitor.online"),
+      ).toBe(false);
+      expect(ValueFormatter.isHigherWorseMetric("service.uptime")).toBe(false);
+      expect(ValueFormatter.isHigherWorseMetric("availability_percent")).toBe(
+        false,
+      );
+    });
+
+    test("returns true for higher-is-worse metrics", () => {
+      expect(ValueFormatter.isHigherWorseMetric("http.error.count")).toBe(true);
+      expect(ValueFormatter.isHigherWorseMetric("incident.count")).toBe(true);
+      expect(ValueFormatter.isHigherWorseMetric("request.latency")).toBe(true);
+      expect(ValueFormatter.isHigherWorseMetric("cpu.utilization")).toBe(true);
+      expect(ValueFormatter.isHigherWorseMetric("pod.restart")).toBe(true);
+    });
+
+    test("returns false for neutral counters and undefined", () => {
+      expect(ValueFormatter.isHigherWorseMetric("network.bytes")).toBe(false);
+      expect(ValueFormatter.isHigherWorseMetric(undefined)).toBe(false);
+    });
+
+    test("higher-is-better token wins over higher-is-worse token", () => {
+      // Contains both "uptime" (better) and would otherwise be neutral.
+      expect(ValueFormatter.isHigherWorseMetric("system.uptime.seconds")).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("isScalableUnit", () => {
+    test("true for known scalable units", () => {
+      expect(ValueFormatter.isScalableUnit("bytes")).toBe(true);
+      expect(ValueFormatter.isScalableUnit("ms")).toBe(true);
+      expect(ValueFormatter.isScalableUnit("By")).toBe(true);
+    });
+
+    test("false for empty or unknown units", () => {
+      expect(ValueFormatter.isScalableUnit("")).toBe(false);
+      expect(ValueFormatter.isScalableUnit("   ")).toBe(false);
+      expect(ValueFormatter.isScalableUnit("%")).toBe(false);
+      expect(ValueFormatter.isScalableUnit("widgets")).toBe(false);
+    });
+  });
+
+  describe("getReadableUnit", () => {
+    test("maps UCUM codes to readable names", () => {
+      expect(ValueFormatter.getReadableUnit("By")).toBe("Bytes");
+      expect(ValueFormatter.getReadableUnit("s")).toBe("Seconds");
+      expect(ValueFormatter.getReadableUnit("ms")).toBe("Milliseconds");
+    });
+
+    test("dimensionless returns empty string", () => {
+      expect(ValueFormatter.getReadableUnit("1")).toBe("");
+      expect(ValueFormatter.getReadableUnit("")).toBe("");
+    });
+
+    test("fraction metric with '1' returns Percent", () => {
+      expect(
+        ValueFormatter.getReadableUnit("1", {
+          metricName: "cpu.utilization",
+        }),
+      ).toBe("Percent");
+    });
+
+    test("percent variants return Percent", () => {
+      expect(ValueFormatter.getReadableUnit("%")).toBe("Percent");
+      expect(ValueFormatter.getReadableUnit("pct")).toBe("Percent");
+    });
+
+    test("annotation-only unit is capitalized", () => {
+      expect(ValueFormatter.getReadableUnit("{thread}")).toBe("Thread");
+      expect(ValueFormatter.getReadableUnit("{packets}")).toBe("Packets");
+    });
+
+    test("compound rate unit reads as 'X per Y' with singular denominator", () => {
+      expect(ValueFormatter.getReadableUnit("By/s")).toBe("Bytes per Second");
+    });
+
+    test("unknown unit is returned unchanged", () => {
+      expect(ValueFormatter.getReadableUnit("widgets")).toBe("widgets");
+    });
+  });
+});

package/Types/AnalyticsDatabase/AnalyticsTableName.ts

@@ -8,6 +8,7 @@ enum AnalyticsTableName {
   Profile = "ProfileItemV3",
   ProfileSample = "ProfileSampleItemV3",
   AuditLog = "AuditLogV2",
+  KubernetesCostAllocation = "KubernetesCostAllocationV1",
   /*
    * Materialized-view target tables. These hold AggregateFunction
    * states populated by attached MVs on the source `Metric` table.
@@ -33,6 +34,15 @@ enum AnalyticsTableName {
   MetricItemAggMV1mByContainer = "MetricItemAggMV1mByContainer",
   MetricBaselineHourly = "MetricBaselineHourly",
   MutableMetric = "MutableMetricItem",
+  /*
+   * SLO / Error Budget history rollup. ReplacingMergeTree keyed by
+   * (projectId, sloId, metricName, bucketStart) with a `version` column
+   * so at-least-once evaluator writes and trailing re-writes dedupe to
+   * the latest value. Deliberately NOT MetricItemV3: its own monthly
+   * partitions + 400-day TTL keep long-lived SLO rows from pinning the
+   * daily raw-telemetry partitions (ttl_only_drop_parts hazard).
+   */
+  SloHistory = "SloHistory",
 }
 
 export default AnalyticsTableName;

package/Types/AnalyticsDatabase/TableColumn.ts

@@ -213,6 +213,27 @@ export default class AnalyticsTableColumn {
     this._aggregateFunctionDefinition = v;
   }
 
+  /*
+   * Optional ClickHouse SimpleAggregateFunction wrapper for scalar columns.
+   *
+   * Unlike AggregateFunction, a SimpleAggregateFunction keeps the scalar's
+   * ordinary wire/query type (for example DateTime) while teaching
+   * AggregatingMergeTree how to combine values during background merges.
+   * `max` on a DateTime retention column is the canonical use: reads and TTLs
+   * still see a DateTime, but rows sharing the sort key retain the latest
+   * expiry instead of an arbitrary one.
+   *
+   * The underlying type comes from `type`; this field contains only the
+   * function name, e.g. "max".
+   */
+  private _simpleAggregateFunction: string | undefined;
+  public get simpleAggregateFunction(): string | undefined {
+    return this._simpleAggregateFunction;
+  }
+  public set simpleAggregateFunction(v: string | undefined) {
+    this._simpleAggregateFunction = v;
+  }
+
   public constructor(data: {
     key: string;
     title: string;
@@ -232,6 +253,7 @@ export default class AnalyticsTableColumn {
     isLowCardinality?: boolean | undefined;
     mapKeysColumn?: string | undefined;
     aggregateFunctionDefinition?: string | undefined;
+    simpleAggregateFunction?: string | undefined;
   }) {
     this.accessControl = data.accessControl;
     this.key = data.key;
@@ -250,5 +272,6 @@ export default class AnalyticsTableColumn {
     this.isLowCardinality = data.isLowCardinality || false;
     this.mapKeysColumn = data.mapKeysColumn;
     this.aggregateFunctionDefinition = data.aggregateFunctionDefinition;
+    this.simpleAggregateFunction = data.simpleAggregateFunction;
   }
 }

package/Types/BaseDatabase/EqualTo.ts

@@ -15,7 +15,15 @@ export default class EqualTo<T extends CompareType> extends CompareBase<T> {
   public override toJSON(): JSONObject {
     return {
       _type: ObjectType.EqualTo,
-      value: (this as EqualTo<T>).toString(),
+      /*
+       * The RAW value is serialized (like GreaterThan / InBetween), not
+       * toString(): toString() stringifies a Date into a locale- and
+       * timezone-dependent form that loses milliseconds, and coerces a number
+       * into a string. JSON.stringify emits a raw Date as its full ISO
+       * timestamp, which the server binds at full precision — and which is
+       * what lets an equality filter survive a round trip through the URL.
+       */
+      value: (this as EqualTo<T>).value,
     };
   }
 

package/Types/BaseDatabase/EqualToOrNull.ts

@@ -17,7 +17,15 @@ export default class EqualToOrNull<
   public override toJSON(): JSONObject {
     return {
       _type: ObjectType.EqualToOrNull,
-      value: (this as EqualToOrNull<T>).toString(),
+      /*
+       * The RAW value is serialized (like GreaterThan / InBetween), not
+       * toString(): toString() stringifies a Date into a locale- and
+       * timezone-dependent form that loses milliseconds, and coerces a number
+       * into a string. JSON.stringify emits a raw Date as its full ISO
+       * timestamp, which the server binds at full precision — and which is
+       * what lets an equality filter survive a round trip through the URL.
+       */
+      value: (this as EqualToOrNull<T>).value,
     };
   }
 

package/Types/BaseDatabase/NotEqual.ts

@@ -14,7 +14,15 @@ export default class NotEqual<T extends CompareType> extends CompareBase<T> {
   public override toJSON(): JSONObject {
     return {
       _type: ObjectType.NotEqual,
-      value: (this as NotEqual<T>).toString(),
+      /*
+       * The RAW value is serialized (like GreaterThan / InBetween), not
+       * toString(): toString() stringifies a Date into a locale- and
+       * timezone-dependent form that loses milliseconds, and coerces a number
+       * into a string. JSON.stringify emits a raw Date as its full ISO
+       * timestamp, which the server binds at full precision — and which is
+       * what lets an equality filter survive a round trip through the URL.
+       */
+      value: (this as NotEqual<T>).value,
     };
   }
 

package/Types/Dashboard/DashboardComponentType.ts

@@ -12,6 +12,7 @@ enum DashboardComponentType {
   IncidentList = `IncidentList`,
   AlertList = `AlertList`,
   MonitorList = `MonitorList`,
+  Slo = `Slo`,
   KubernetesPodList = `KubernetesPodList`,
   KubernetesNodeList = `KubernetesNodeList`,
   KubernetesNamespaceList = `KubernetesNamespaceList`,

package/Types/Dashboard/DashboardComponents/ComponentArgument.ts

@@ -27,6 +27,7 @@ export enum EntityFilterModelType {
   AlertState = "AlertState",
   MonitorStatus = "MonitorStatus",
   Monitor = "Monitor",
+  ServiceLevelObjective = "ServiceLevelObjective",
   Label = "Label",
   KubernetesCluster = "KubernetesCluster",
   DockerHost = "DockerHost",

package/Types/Dashboard/DashboardComponents/DashboardSloComponent.ts

@@ -0,0 +1,42 @@
+import ObjectID from "../../ObjectID";
+import DashboardComponentType from "../DashboardComponentType";
+import BaseComponent from "./DashboardBaseComponent";
+
+/**
+ * Which of the SLO's three tracked numbers the widget renders.
+ *
+ * These values are persisted inside the dashboard's JSON config, so they
+ * must never be renamed — only added to.
+ */
+export enum SloWidgetMetric {
+  Sli = "Sli",
+  ErrorBudgetRemaining = "ErrorBudgetRemaining",
+  BurnRate = "BurnRate",
+}
+
+/**
+ * Tile renders the single current number (read from the SLO row that the
+ * evaluation worker keeps up to date). Chart renders the SloHistory
+ * series for the same metric over the dashboard's selected time range.
+ */
+export enum SloWidgetDisplayType {
+  Tile = "Tile",
+  Chart = "Chart",
+}
+
+export default interface DashboardSloComponent extends BaseComponent {
+  componentType: DashboardComponentType.Slo;
+  componentId: ObjectID;
+  arguments: {
+    /*
+     * ObjectID of the ServiceLevelObjective, held as a string because the
+     * EntityDropdown argument editor writes the raw `_id` and the whole
+     * component tree round-trips through the dashboard's JSON config.
+     * The renderer wraps it in `new ObjectID(...)` before querying.
+     */
+    serviceLevelObjectiveId?: string | undefined;
+    sloMetric?: SloWidgetMetric | undefined;
+    displayType?: SloWidgetDisplayType | undefined;
+    widgetTitle?: string | undefined;
+  };
+}