@oneuptime/common 11.6.1 → 11.7.0

package/Utils/NetworkSite/SiteStatusRollupUtil.ts

@@ -0,0 +1,97 @@
+/*
+ * Worst-of health rollup for a NetworkSite's device subtree.
+ *
+ * Each device contributes one MonitorStatus candidate and the highest
+ * priority number wins - MonitorStatus.priority is HIGHER = WORSE per the
+ * seeded rows (Operational 1 ... Offline 3), regardless of what the column
+ * docstring claims. Pure so the whole decision matrix is unit-testable.
+ */
+
+// One device's health inputs, denormalized by the rollup engine.
+export interface DeviceHealthState {
+  /*
+   * The MonitorStatus stamped by the monitor bridge (string form). When set
+   * together with its priority, it is the device's authoritative status.
+   */
+  currentMonitorStatusId?: string | null | undefined;
+  // Priority of that status row; missing when the row no longer exists.
+  monitorStatusPriority?: number | null | undefined;
+  // Last SNMP contact; drives the freshness fallback for unmonitored devices.
+  lastSeenAt?: Date | null | undefined;
+}
+
+// A project MonitorStatus row a freshness fallback can resolve to.
+export interface RollupStatusOption {
+  monitorStatusId: string;
+  priority: number;
+}
+
+export class SiteStatusRollupUtil {
+  // A device is considered alive when SNMP data arrived within this window.
+  public static readonly DEFAULT_FRESHNESS_WINDOW_IN_MINUTES: number = 15;
+
+  /*
+   * Returns the winning MonitorStatus id for a set of devices, or null when
+   * no device contributes anything (empty subtree, or freshness fallbacks
+   * unavailable because the project has no operational/offline rows) - the
+   * caller treats null as "leave the site's status untouched".
+   *
+   * Per device: a stamped monitor status (with a known priority) wins;
+   * otherwise lastSeenAt within the freshness window maps to the project's
+   * isOperationalState row and anything staler (or never seen) maps to the
+   * isOfflineState row. Priority ties keep the first contributor (stable).
+   */
+  public static worstStatus(data: {
+    deviceStates: Array<DeviceHealthState>;
+    operationalStatus?: RollupStatusOption | null | undefined;
+    offlineStatus?: RollupStatusOption | null | undefined;
+    now?: Date | undefined;
+    freshnessWindowInMinutes?: number | undefined;
+  }): string | null {
+    const now: Date = data.now || new Date();
+    const windowInMinutes: number =
+      data.freshnessWindowInMinutes ??
+      SiteStatusRollupUtil.DEFAULT_FRESHNESS_WINDOW_IN_MINUTES;
+    const windowInMs: number = windowInMinutes * 60 * 1000;
+
+    let winner: RollupStatusOption | null = null;
+
+    for (const device of data.deviceStates) {
+      let candidate: RollupStatusOption | null = null;
+
+      if (
+        device.currentMonitorStatusId &&
+        typeof device.monitorStatusPriority === "number" &&
+        Number.isFinite(device.monitorStatusPriority)
+      ) {
+        candidate = {
+          monitorStatusId: device.currentMonitorStatusId,
+          priority: device.monitorStatusPriority,
+        };
+      } else {
+        const lastSeenAtInMs: number | null = device.lastSeenAt
+          ? new Date(device.lastSeenAt).getTime()
+          : null;
+        const isFresh: boolean =
+          lastSeenAtInMs !== null &&
+          now.getTime() - lastSeenAtInMs <= windowInMs;
+
+        candidate = isFresh
+          ? data.operationalStatus || null
+          : data.offlineStatus || null;
+      }
+
+      if (!candidate) {
+        continue;
+      }
+
+      if (!winner || candidate.priority > winner.priority) {
+        winner = candidate;
+      }
+    }
+
+    return winner ? winner.monitorStatusId : null;
+  }
+}
+
+export default SiteStatusRollupUtil;

package/Utils/NetworkSite/SiteUptimeUtil.ts

@@ -0,0 +1,111 @@
+/*
+ * Uptime percentage over a NetworkSiteStatusTimeline window.
+ *
+ * Every row whose status is not flagged operational counts as downtime.
+ * Rows are clamped to the window, an open row (endsAt null) extends to the
+ * window end, and overlapping down rows are merged so no second is counted
+ * twice. Time not covered by any row counts as up - the timeline only gains
+ * rows once a rollup has run, and absence of evidence is not an outage.
+ */
+
+// One timeline row, denormalized with its status row's priority and flag.
+export interface SiteStatusTimelineRow {
+  monitorStatusId: string;
+  startsAt: Date;
+  endsAt: Date | null;
+  priority: number;
+  isOperationalState: boolean;
+}
+
+interface TimeInterval {
+  startInMs: number;
+  endInMs: number;
+}
+
+export class SiteUptimeUtil {
+  /*
+   * Percent of [windowStart, windowEnd) the site was NOT in a
+   * non-operational status. Returns 100 for an empty or inverted window.
+   * The result is exact (not rounded) and clamped to 0..100.
+   */
+  public static calculateUptimePercent(
+    rows: Array<SiteStatusTimelineRow>,
+    windowStart: Date,
+    windowEnd: Date,
+  ): number {
+    const windowStartInMs: number = windowStart.getTime();
+    const windowEndInMs: number = windowEnd.getTime();
+    const windowInMs: number = windowEndInMs - windowStartInMs;
+
+    if (!Number.isFinite(windowInMs) || windowInMs <= 0) {
+      return 100;
+    }
+
+    const downIntervals: Array<TimeInterval> = [];
+
+    for (const row of rows) {
+      if (row.isOperationalState) {
+        continue;
+      }
+
+      const rowStartInMs: number = new Date(row.startsAt).getTime();
+      const rowEndInMs: number = row.endsAt
+        ? new Date(row.endsAt).getTime()
+        : windowEndInMs;
+
+      if (!Number.isFinite(rowStartInMs) || !Number.isFinite(rowEndInMs)) {
+        continue;
+      }
+
+      const clampedStartInMs: number = Math.max(rowStartInMs, windowStartInMs);
+      const clampedEndInMs: number = Math.min(rowEndInMs, windowEndInMs);
+
+      if (clampedEndInMs <= clampedStartInMs) {
+        continue;
+      }
+
+      downIntervals.push({
+        startInMs: clampedStartInMs,
+        endInMs: clampedEndInMs,
+      });
+    }
+
+    const downInMs: number = SiteUptimeUtil.totalCoveredMs(downIntervals);
+
+    const uptimePercent: number = ((windowInMs - downInMs) / windowInMs) * 100;
+    return Math.min(100, Math.max(0, uptimePercent));
+  }
+
+  // Sum of interval lengths after merging overlaps.
+  private static totalCoveredMs(intervals: Array<TimeInterval>): number {
+    if (intervals.length === 0) {
+      return 0;
+    }
+
+    const sorted: Array<TimeInterval> = [...intervals].sort(
+      (a: TimeInterval, b: TimeInterval) => {
+        return a.startInMs - b.startInMs;
+      },
+    );
+
+    let totalInMs: number = 0;
+    let currentStartInMs: number = sorted[0]!.startInMs;
+    let currentEndInMs: number = sorted[0]!.endInMs;
+
+    for (let i: number = 1; i < sorted.length; i++) {
+      const interval: TimeInterval = sorted[i]!;
+      if (interval.startInMs <= currentEndInMs) {
+        currentEndInMs = Math.max(currentEndInMs, interval.endInMs);
+      } else {
+        totalInMs += currentEndInMs - currentStartInMs;
+        currentStartInMs = interval.startInMs;
+        currentEndInMs = interval.endInMs;
+      }
+    }
+
+    totalInMs += currentEndInMs - currentStartInMs;
+    return totalInMs;
+  }
+}
+
+export default SiteUptimeUtil;

package/Utils/Slo/SloBurnRateRuleState.ts

@@ -0,0 +1,91 @@
+/**
+ * Whether a burn rate rule currently has an alert open.
+ *
+ * `lastAlertCreatedAt` / `lastAlertResolvedAt` are stamped by the
+ * evaluation worker every time it fires or resolves a rule's alert, and
+ * together they are the only record of the rule's lifecycle — but nothing
+ * read them outside the worker, so the Burn Rate Rules table could not
+ * tell the user whether a rule was paging someone right now, had ever
+ * fired, or had never once triggered.
+ *
+ * The predicate is the worker's own (EvaluateSlos.evaluateBurnRateRule's
+ * `hasUnresolvedFiringState`), lifted here so the table and the worker can
+ * never disagree about what "firing" means.
+ *
+ * Kept free of React and of the database model so both can import it and
+ * so the ordering edges are unit-testable without a DOM.
+ */
+
+import SloStatus from "../../Types/ServiceLevelObjective/SloStatus";
+
+export interface SloBurnRateRuleAlertState {
+  lastAlertCreatedAt?: Date | undefined | null;
+  lastAlertResolvedAt?: Date | undefined | null;
+}
+
+/**
+ * True when the rule has fired and that alert has not been resolved
+ * since.
+ *
+ * A resolve stamped at exactly the same instant as the fire counts as
+ * resolved: the worker writes the resolve strictly after the fire, so an
+ * equal pair can only be the same lifecycle, and treating it as firing
+ * would leave a red "Firing" pill on a rule with nothing open.
+ */
+export type IsBurnRateRuleFiringFunction = (
+  rule: SloBurnRateRuleAlertState,
+) => boolean;
+
+export const isBurnRateRuleFiring: IsBurnRateRuleFiringFunction = (
+  rule: SloBurnRateRuleAlertState,
+): boolean => {
+  if (!rule.lastAlertCreatedAt) {
+    return false;
+  }
+
+  if (!rule.lastAlertResolvedAt) {
+    return true;
+  }
+
+  return rule.lastAlertResolvedAt.getTime() < rule.lastAlertCreatedAt.getTime();
+};
+
+/**
+ * Whether the OWNING SLO is in a state where a burn rate rule could be
+ * firing at all.
+ *
+ * `isBurnRateRuleFiring` alone is not enough to render a live "Firing"
+ * badge. When an SLO is disabled, or the worker's guards move it to
+ * Misconfigured or Paused, the SLO-level resolve paths
+ * (ServiceLevelObjectiveService.resolveOpenBurnRateAlertsForSlo and the
+ * worker's setGuardStatusAndResolveOpenAlerts) close every open alert but
+ * deliberately do NOT stamp `lastAlertResolvedAt` — that column drives a
+ * live rule's re-fire suppression, and this is a state change of the SLO
+ * rather than a burn rate that recovered. The rule's own columns are
+ * therefore left mid-lifecycle, and a UI reading them alone would show a
+ * red "Firing" pill on a rule with nothing open, forever.
+ *
+ * Pairing the two predicates keeps the badge honest without touching the
+ * suppression semantics the worker depends on.
+ */
+export interface SloBurnRateFiringContext {
+  isEnabled?: boolean | undefined | null;
+  sloStatus?: SloStatus | undefined | null;
+}
+
+export type CanSloFireBurnRateAlertsFunction = (
+  slo: SloBurnRateFiringContext,
+) => boolean;
+
+export const canSloFireBurnRateAlerts: CanSloFireBurnRateAlertsFunction = (
+  slo: SloBurnRateFiringContext,
+): boolean => {
+  if (slo.isEnabled === false) {
+    return false;
+  }
+
+  return (
+    slo.sloStatus !== SloStatus.Misconfigured &&
+    slo.sloStatus !== SloStatus.Paused
+  );
+};

package/Utils/Slo/SloDuration.ts

@@ -0,0 +1,165 @@
+/**
+ * Compact duration rendering for error budgets.
+ *
+ * Error budgets span four orders of magnitude — a 99.99% / 7-day SLO gets
+ * 60 seconds, a 99% / 90-day SLO gets 21.6 hours — so the "minutes only"
+ * rendering the SLO pages started with reads badly at both ends: a
+ * one-minute budget shows as "1 min", and a 90-day budget shows as
+ * "1296 min of 1296 min". The docs quote budgets the way an SRE says them
+ * out loud ("43m 12s", "2h 9m"), and this is the helper that produces
+ * exactly that.
+ *
+ * Kept free of React (and of the database models) so the SLO pages, the
+ * dashboard SLO widget and any future status-page surface can all share
+ * one rendering, and so every rounding edge is unit-testable without a
+ * DOM.
+ */
+
+/** U+2212 MINUS SIGN — reads as a minus rather than a hyphen at tile sizes. */
+const MINUS_SIGN: string = "−";
+
+/**
+ * Seconds per unit, largest first. Only the two most significant non-zero
+ * units are rendered: "2d 5h" is what an on-call engineer needs, "2d 5h
+ * 13m 7s" is noise, and truncating rather than rounding up keeps the
+ * remaining budget from ever reading larger than it is.
+ */
+const UNITS: Array<{ suffix: string; seconds: number }> = [
+  { suffix: "d", seconds: 86400 },
+  { suffix: "h", seconds: 3600 },
+  { suffix: "m", seconds: 60 },
+  { suffix: "s", seconds: 1 },
+];
+
+const MAX_UNITS_SHOWN: number = 2;
+
+/**
+ * `null` for anything that is not a real, finite number. The
+ * worker-owned budget columns are NULL until the SLO is first evaluated,
+ * and a Postgres decimal can arrive as a string over JSON, so the guard
+ * has to reject non-numbers rather than coerce them.
+ */
+type ToFiniteNumberFunction = (
+  value: number | undefined | null,
+) => number | null;
+
+const toFiniteNumber: ToFiniteNumberFunction = (
+  value: number | undefined | null,
+): number | null => {
+  if (typeof value !== "number" || !isFinite(value)) {
+    return null;
+  }
+
+  return value;
+};
+
+/**
+ * An unsigned duration as "2d 5h" / "43m 12s" / "45s". Fractional seconds
+ * are floored, so a 59.9-second budget renders "59s" rather than rounding
+ * up to a minute the SLO does not actually have.
+ *
+ * A duration that floors to zero renders "0s" — a real, sayable state —
+ * instead of an empty string.
+ */
+export type FormatDurationCompactFunction = (seconds: number) => string;
+
+export const formatDurationCompact: FormatDurationCompactFunction = (
+  seconds: number,
+): string => {
+  let remainingSeconds: number = Math.floor(Math.abs(seconds));
+
+  const parts: Array<string> = [];
+
+  for (const unit of UNITS) {
+    if (parts.length >= MAX_UNITS_SHOWN) {
+      break;
+    }
+
+    const count: number = Math.floor(remainingSeconds / unit.seconds);
+
+    /*
+     * Skip leading zero units ("0d 5h"), but once a larger unit has been
+     * emitted a zero is still skipped rather than padded — "2d" is
+     * correct for exactly 48 hours, "2d 0h" is not how anyone says it.
+     */
+    if (count <= 0) {
+      continue;
+    }
+
+    parts.push(`${count}${unit.suffix}`);
+    remainingSeconds -= count * unit.seconds;
+  }
+
+  if (parts.length === 0) {
+    return "0s";
+  }
+
+  return parts.join(" ");
+};
+
+/**
+ * `errorBudgetRemainingSeconds` is SIGNED: negative means the budget is
+ * overspent, and that overage is the single most useful number during a
+ * bad month. Render it plainly rather than clamping to zero, which would
+ * hide a breach.
+ *
+ * Returns `null` (not a placeholder string) when the SLO has not been
+ * evaluated, so callers decide how to phrase "no data yet" in their own
+ * context.
+ */
+export type FormatErrorBudgetRemainingFunction = (
+  seconds: number | undefined | null,
+) => string | null;
+
+export const formatErrorBudgetRemaining: FormatErrorBudgetRemainingFunction = (
+  seconds: number | undefined | null,
+): string | null => {
+  const numericSeconds: number | null = toFiniteNumber(seconds);
+
+  if (numericSeconds === null) {
+    return null;
+  }
+
+  if (numericSeconds < 0) {
+    return `${MINUS_SIGN}${formatDurationCompact(numericSeconds)} over budget`;
+  }
+
+  return `${formatDurationCompact(numericSeconds)} left`;
+};
+
+/**
+ * "12m 30s left of 43m 12s" — the phrasing the error-budget docs use.
+ * Falls back to the bare remaining string when the total is not known
+ * (the two columns are written together by the worker, but a partially
+ * evaluated row must not render "of null").
+ */
+export type FormatErrorBudgetRemainingOfTotalFunction = (data: {
+  remainingSeconds: number | undefined | null;
+  totalSeconds: number | undefined | null;
+}) => string | null;
+
+export const formatErrorBudgetRemainingOfTotal: FormatErrorBudgetRemainingOfTotalFunction =
+  (data: {
+    remainingSeconds: number | undefined | null;
+    totalSeconds: number | undefined | null;
+  }): string | null => {
+    const remainingText: string | null = formatErrorBudgetRemaining(
+      data.remainingSeconds,
+    );
+
+    if (remainingText === null) {
+      return null;
+    }
+
+    const totalSeconds: number | null = toFiniteNumber(data.totalSeconds);
+
+    /*
+     * A zero total is a real state for a brand-new SLO (no elapsed window
+     * yet). "of 0s" adds nothing, so drop the suffix rather than print it.
+     */
+    if (totalSeconds === null || totalSeconds <= 0) {
+      return remainingText;
+    }
+
+    return `${remainingText} of ${formatDurationCompact(totalSeconds)}`;
+  };

package/Utils/Slo/SloEvaluation.ts

@@ -0,0 +1,22 @@
+/**
+ * Cadence constants shared by the SLO evaluation worker and every UI
+ * surface that describes what the worker produced.
+ *
+ * These numbers were previously duplicated as prose: the worker owned
+ * them, and the dashboard said "evaluated every few minutes" and "1×
+ * spends the budget exactly over the window" without ever naming the
+ * lookback the headline burn rate is actually measured over. A reader who
+ * compared the tile against a burn rate rule had no way to know they were
+ * measuring different spans. Naming them once here keeps the copy and the
+ * computation from drifting.
+ */
+
+/** How often a due SLO is re-evaluated, and how far ahead the worker schedules the next run. */
+export const SLO_EVALUATION_CADENCE_MINUTES: number = 5;
+
+/**
+ * Lookback for the "current burn rate" column shown on the SLO overview
+ * and the dashboard SLO widget. Deliberately equal to the default
+ * fast-burn rule's long window, so the tile and that rule move together.
+ */
+export const SLO_CURRENT_BURN_RATE_WINDOW_MINUTES: number = 60;