@oneuptime/common 13.0.5 → 13.0.6

package/Utils/Slo/SloHealth.ts

@@ -102,11 +102,34 @@ export enum SloNoticeType {
   Danger = "Danger",
 }
 
+/**
+ * Where a notice's call to action leads. Named by destination rather than
+ * carrying a route: this module is imported by plain-node tests and by the
+ * dashboard SLO widget, and RouteMap reads `window` at module load. The
+ * banner, which already lives in the Dashboard, turns a target into a link.
+ */
+export enum SloNoticeActionTarget {
+  Settings = "settings",
+  Monitors = "monitors",
+  MonitorRules = "monitor-rules",
+}
+
+export interface SloNoticeAction {
+  /** Short link text naming what the user will do there. */
+  label: string;
+  target: SloNoticeActionTarget;
+}
+
 export interface SloNotice {
   type: SloNoticeType;
   title: string;
   /** One sentence of "here is what to do about it". */
   body: string;
+  /**
+   * The page where the user can fix it. Absent when there is nothing to
+   * do but wait, or when no page in the product can fix it.
+   */
+  action?: SloNoticeAction | undefined;
 }
 
 /**
@@ -115,6 +138,7 @@ export interface SloNotice {
  * tests can pass plain objects.
  */
 export interface SloNoticeData {
+  isArchived?: boolean | undefined | null;
   isEnabled?: boolean | undefined | null;
   sloStatus?: SloStatus | undefined | null;
   sliType?: SliType | undefined | null;
@@ -126,6 +150,20 @@ export interface SloNoticeData {
   lastEvaluatedAt?: Date | string | undefined | null;
 }
 
+type GetNoMonitorsNoticeFunction = () => SloNotice;
+
+const getNoMonitorsNotice: GetNoMonitorsNoticeFunction = (): SloNotice => {
+  return {
+    type: SloNoticeType.Warning,
+    title: "No monitors attached",
+    body: "An SLO measures uptime from its monitors, so it cannot be evaluated without at least one. Attach monitors on the Monitors page, or add a monitor rule that attaches matching monitors for you.",
+    action: {
+      label: "Attach monitors",
+      target: SloNoticeActionTarget.Monitors,
+    },
+  };
+};
+
 /**
  * The single most important thing to tell the user about this SLO right
  * now, or null when the SLO is measuring normally.
@@ -134,9 +172,13 @@ export interface SloNoticeData {
  * numbers, so the banner always names the root cause rather than a
  * downstream symptom: a disabled SLO is not evaluated at all, so saying
  * "no monitors attached" would send the user to fix the wrong thing.
+ * Archived comes before disabled for the same reason — turning evaluation
+ * back on does not bring an SLO out of the archive, so it would still
+ * measure nothing.
  *
  * Every branch mirrors a guard in the evaluation worker
  * (App/FeatureSet/Workers/Jobs/Slo/EvaluateSlos.ts):
+ *   isArchived=true      -> the SLO is skipped entirely by getDueSlos()
  *   isEnabled=false      -> the SLO is skipped entirely by getDueSlos()
  *   sliType != Uptime    -> Misconfigured (Metric SLIs are not built yet)
  *   monitorCount == 0    -> Misconfigured
@@ -148,17 +190,37 @@ export type GetSloNoticeFunction = (data: SloNoticeData) => SloNotice | null;
 export const getSloNotice: GetSloNoticeFunction = (
   data: SloNoticeData,
 ): SloNotice | null => {
+  if (data.isArchived === true) {
+    return {
+      type: SloNoticeType.Info,
+      title: "This SLO is archived",
+      body: "Archived SLOs are hidden from the SLO list and are not evaluated, so its numbers are frozen and its burn rate rules will not fire. Unarchive it in Settings to resume measuring.",
+      action: {
+        label: "Open Settings",
+        target: SloNoticeActionTarget.Settings,
+      },
+    };
+  }
+
   if (data.isEnabled === false) {
     return {
       type: SloNoticeType.Info,
       title: "This SLO is disabled",
-      body: "It is not being evaluated and its burn rate rules will not fire alerts. Turn Enabled back on in SLO Details to resume measuring.",
+      body: "It is not being evaluated and its burn rate rules will not fire alerts. Turn evaluation back on in Settings to resume measuring.",
+      action: {
+        label: "Open Settings",
+        target: SloNoticeActionTarget.Settings,
+      },
     };
   }
 
   const monitorCount: number = toFiniteNumber(data.monitorCount) ?? 0;
 
   if (data.sloStatus === SloStatus.Misconfigured) {
+    /*
+     * No action: the SLI type is not editable anywhere in the product, so
+     * a link would lead to a page that cannot fix this.
+     */
     if (data.sliType && data.sliType !== SliType.MonitorUptime) {
       return {
         type: SloNoticeType.Warning,
@@ -168,11 +230,7 @@ export const getSloNotice: GetSloNoticeFunction = (
     }
 
     if (monitorCount === 0) {
-      return {
-        type: SloNoticeType.Warning,
-        title: "No monitors attached",
-        body: "An SLO measures uptime from its monitors, so it cannot be evaluated without at least one. Add monitors in SLO Details below.",
-      };
+      return getNoMonitorsNotice();
     }
 
     const target: number | null = toFiniteNumber(data.targetPercentage);
@@ -181,14 +239,27 @@ export const getSloNotice: GetSloNoticeFunction = (
       return {
         type: SloNoticeType.Warning,
         title: "The target is out of range",
-        body: "A target must be greater than 0 and less than 100 — a 100% target leaves no error budget to track. Set a target such as 99.9 in SLO Details below.",
+        body: "A target must be greater than 0 and less than 100 — a 100% target leaves no error budget to track. Set a target such as 99.9 in Settings.",
+        action: {
+          label: "Edit objective",
+          target: SloNoticeActionTarget.Settings,
+        },
       };
     }
 
+    /*
+     * What is left are the worker's two data guards: the attached monitors
+     * no longer exist, or none of them has reported a status yet. Both are
+     * answered on the Monitors page.
+     */
     return {
       type: SloNoticeType.Warning,
       title: "This SLO cannot be evaluated",
-      body: "Check that it has monitors attached and a target below 100%, then wait a few minutes for the next evaluation.",
+      body: "Check that its monitors still exist and have started reporting a status, then wait a few minutes for the next evaluation.",
+      action: {
+        label: "Review monitors",
+        target: SloNoticeActionTarget.Monitors,
+      },
     };
   }
 
@@ -197,10 +268,26 @@ export const getSloNotice: GetSloNoticeFunction = (
       type: SloNoticeType.Info,
       title: "Measurement is paused",
       body: "Every monitor attached to this SLO has active monitoring disabled — by hand, by a manual incident, or by a scheduled maintenance event — so there is no signal to measure. The SLO resumes automatically when a monitor starts reporting again.",
+      action: {
+        label: "View monitors",
+        target: SloNoticeActionTarget.Monitors,
+      },
     };
   }
 
   if (!data.lastEvaluatedAt) {
+    /*
+     * The create form no longer picks monitors, so a brand-new SLO starts
+     * with none, and the worker's first pass will mark it Misconfigured for
+     * exactly that reason. Saying so now, instead of "numbers will appear
+     * shortly", points the user at the one step that makes numbers appear.
+     * Only an explicit, loaded 0 counts: a caller that did not select the
+     * monitors has not told us anything.
+     */
+    if (toFiniteNumber(data.monitorCount) === 0) {
+      return getNoMonitorsNotice();
+    }
+
     return {
       type: SloNoticeType.Info,
       title: "Not evaluated yet",
@@ -236,7 +323,7 @@ export const getSloNotice: GetSloNoticeFunction = (
  *   may not have loaded, say nothing — a missing hint beats a wrong one.
  *
  * The 1% tolerance absorbs the gap between "now" and the worker's last
- * evaluation — without it, a fully mature SLO would flicker the banner on
+ * evaluation — without it, a fully mature SLO would flicker the flag on
  * every evaluation cycle.
  */
 const WINDOW_FULL_TOLERANCE_FRACTION: number = 0.99;

package/Utils/Slo/SloListWidgetFormat.ts

@@ -0,0 +1,370 @@
+import { Gray500, Green, Red, Yellow } from "../../Types/BrandColors";
+import Includes from "../../Types/BaseDatabase/Includes";
+import SortOrder from "../../Types/BaseDatabase/SortOrder";
+import Color from "../../Types/Color";
+import SloStatus from "../../Types/ServiceLevelObjective/SloStatus";
+import { getSloStatusColor, getSloStatusText } from "./SloStatusColor";
+import { SLO_METRIC_SLO_NAME_ATTRIBUTE } from "./SloMetricType";
+import {
+  formatErrorBudgetRemainingSeconds,
+  formatSloBurnRate,
+  formatSloPercent,
+  SloWidgetStateData,
+} from "./SloWidgetFormat";
+
+/**
+ * Pure display rules for the dashboard SLO List widget — every objective in a
+ * project with its status, SLI, error budget and burn rate.
+ *
+ * Kept out of the React renderer so the same ordering, grouping and
+ * formatting can be unit-tested without a DOM, and so the public-dashboard
+ * policy on the server shares the list's sort and variable mapping with the
+ * browser instead of keeping a second copy that could drift.
+ */
+
+/*
+ * Enabled objectives first, then least error budget first. An SLO review
+ * starts with the objectives closest to (or past) breaching, so the list is
+ * ordered server-side by the number that says so — which also means a list
+ * capped by maxRows drops the HEALTHIEST objectives, never the ones in
+ * trouble.
+ *
+ * A disabled SLO is not evaluated, so its budget is frozen at whatever it was
+ * when it was switched off. Left in the budget ordering, an SLO disabled while
+ * overspent would hold the top row indefinitely as the "most urgent"
+ * objective. Postgres sorts false before true, so `isEnabled` DESCENDING puts
+ * every live objective ahead of every disabled one (the column is NOT NULL, so
+ * no NULLs-first surprise), and a capped list drops the disabled rows first.
+ *
+ * Postgres sorts NULLs last on an ascending order, so SLOs the evaluation
+ * worker has not reached yet fall below the measured ones rather than
+ * masquerading as the most urgent. Name breaks ties so equal budgets list
+ * stably.
+ */
+export const SLO_LIST_SORT: { [key: string]: SortOrder } = {
+  isEnabled: SortOrder.Descending,
+  errorBudgetRemainingPercentage: SortOrder.Ascending,
+  name: SortOrder.Ascending,
+};
+
+/*
+ * The list reads Postgres, not the metric store, so a TelemetryAttribute
+ * variable reaches it only through DashboardModelQueryInterpolation — which
+ * needs to be told which column an attribute key means. The `sloName`
+ * attribute every `oneuptime.slo.*` series carries is the SLO's `name`
+ * column, so picking an SLO in the toolbar narrows this list to that
+ * objective, exactly as it narrows the SLO metric charts beside it.
+ */
+export const SLO_LIST_ATTRIBUTE_TO_COLUMN: Record<string, string> = {
+  [SLO_METRIC_SLO_NAME_ATTRIBUTE]: "name",
+};
+
+export const SLO_LIST_DEFAULT_MAX_ROWS: number = 50;
+
+export const SLO_NOT_EVALUATED_STATUS_LABEL: string = "Not Evaluated";
+
+// The same word the SLOs page puts on a disabled SLO's status pill.
+export const SLO_DISABLED_STATUS_LABEL: string = "Disabled";
+
+/*
+ * One list row: the single-SLO widget's display fields plus whether the SLO
+ * is enabled, which only the list needs (a list of objectives can hold a
+ * disabled one; a widget pointed at one objective shows that objective).
+ */
+export interface SloListRowData extends SloWidgetStateData {
+  isEnabled?: boolean | undefined | null;
+}
+
+export type IsSloListRowDisabledFunction = (slo: SloListRowData) => boolean;
+
+/*
+ * Only an explicit false is disabled, exactly as on the SLOs page
+ * (getSloListStatusKind). The column is NOT NULL and defaults to true, so a
+ * row without it was read without the column, not switched off.
+ */
+export const isSloListRowDisabled: IsSloListRowDisabledFunction = (
+  slo: SloListRowData,
+): boolean => {
+  return slo.isEnabled === false;
+};
+
+/*
+ * The widget's stored status filter as query predicates. The browser list and
+ * the public-dashboard policy both build their query from this, so the two
+ * cannot narrow differently.
+ *
+ * A status filter matches ENABLED SLOs only. A disabled SLO keeps the status
+ * it had when it was switched off and the list shows it as Disabled, so a
+ * "Budget Exhausted" filter must not pull in a row that then reads "Disabled"
+ * (the SLOs page's status tiles count enabled SLOs only, for the same reason).
+ * No filter adds nothing, so disabled SLOs stay listed, marked Disabled.
+ *
+ * Validating the values is the caller's job: the server refuses anything not
+ * in SLO_LIST_STATUS_FILTER_VALUES, and the settings form offers nothing else.
+ */
+export type GetSloListStatusFilterQueryFunction = (
+  sloStatuses: Array<string> | undefined | null,
+) => Record<string, unknown>;
+
+export const getSloListStatusFilterQuery: GetSloListStatusFilterQueryFunction =
+  (sloStatuses: Array<string> | undefined | null): Record<string, unknown> => {
+    if (!sloStatuses || sloStatuses.length === 0) {
+      return {};
+    }
+
+    return {
+      sloStatus: new Includes(sloStatuses),
+      isEnabled: true,
+    };
+  };
+
+/*
+ * Burn-rate emphasis. 1x spends the budget exactly over the compliance
+ * window, so anything above it is spending faster than the objective can
+ * sustain. 14.4x is the Google SRE workbook's one-hour paging threshold (2% of
+ * a 30-day budget gone in an hour) — the current burn rate is itself measured
+ * over the trailing hour, so it is the like-for-like line for "page someone".
+ */
+export const SLO_SUSTAINABLE_BURN_RATE: number = 1;
+export const SLO_CRITICAL_BURN_RATE: number = 14.4;
+
+export enum SloBurnRateTone {
+  Unknown = "Unknown",
+  Sustainable = "Sustainable",
+  Elevated = "Elevated",
+  Critical = "Critical",
+}
+
+export type GetSloBurnRateToneFunction = (
+  burnRate: number | undefined | null,
+) => SloBurnRateTone;
+
+export const getSloBurnRateTone: GetSloBurnRateToneFunction = (
+  burnRate: number | undefined | null,
+): SloBurnRateTone => {
+  if (typeof burnRate !== "number" || !isFinite(burnRate)) {
+    return SloBurnRateTone.Unknown;
+  }
+
+  if (burnRate >= SLO_CRITICAL_BURN_RATE) {
+    return SloBurnRateTone.Critical;
+  }
+
+  if (burnRate > SLO_SUSTAINABLE_BURN_RATE) {
+    return SloBurnRateTone.Elevated;
+  }
+
+  return SloBurnRateTone.Sustainable;
+};
+
+/*
+ * Width of the error-budget bar, as a percentage of its track. The stored
+ * percentage is unrounded and goes NEGATIVE once the budget is overspent —
+ * which is a real, displayed number — so only the bar is clamped. A bar
+ * cannot be drawn at −30% of its track, and a budget cannot be more than
+ * whole.
+ */
+export type GetSloBudgetBarFillPercentFunction = (
+  errorBudgetRemainingPercentage: number | undefined | null,
+) => number | null;
+
+export const getSloBudgetBarFillPercent: GetSloBudgetBarFillPercentFunction = (
+  errorBudgetRemainingPercentage: number | undefined | null,
+): number | null => {
+  if (
+    typeof errorBudgetRemainingPercentage !== "number" ||
+    !isFinite(errorBudgetRemainingPercentage)
+  ) {
+    return null;
+  }
+
+  return Math.min(Math.max(errorBudgetRemainingPercentage, 0), 100);
+};
+
+export interface SloListRowDisplay {
+  // SLI to three decimals, or null before the first evaluation.
+  sli: string | null;
+  // "target 99.9%", or null when the SLO has no target.
+  target: string | null;
+  // Error budget remaining to one decimal (may be negative), or null.
+  budget: string | null;
+  // "42 min remaining" / "−10 min over budget", or null.
+  budgetTime: string | null;
+  // 0..100 bar width, or null when there is no budget figure to draw.
+  budgetFillPercent: number | null;
+  // "1.25×", or null.
+  burnRate: string | null;
+  burnRateTone: SloBurnRateTone;
+  statusText: string;
+  statusColor: Color;
+}
+
+/*
+ * Same precision rules as the single-SLO widget (SloWidgetFormat): the SLI
+ * keeps three decimals because 99.95 and 99.9 are different objectives, the
+ * budget percentage one, and the burn rate is a multiplier.
+ */
+export type GetSloListRowDisplayFunction = (
+  slo: SloListRowData,
+) => SloListRowDisplay;
+
+export const getSloListRowDisplay: GetSloListRowDisplayFunction = (
+  slo: SloListRowData,
+): SloListRowDisplay => {
+  const target: string | null = formatSloPercent(slo.targetPercentage, 3);
+
+  /*
+   * A disabled SLO is not evaluated, so its status, budget and burn rate are
+   * frozen at the moment it was switched off. The row keeps those last
+   * numbers — they are what it last measured, and the SLOs page shows them
+   * too — but says Disabled instead of the frozen status, and draws neither a
+   * status-coloured budget bar nor a red or amber burn rate for a number that
+   * is no longer moving.
+   */
+  if (isSloListRowDisabled(slo)) {
+    return {
+      sli: formatSloPercent(slo.currentSliPercentage, 3),
+      target: target === null ? null : `target ${target}`,
+      budget: formatSloPercent(slo.errorBudgetRemainingPercentage, 1),
+      budgetTime: formatErrorBudgetRemainingSeconds(
+        slo.errorBudgetRemainingSeconds,
+      ),
+      budgetFillPercent: getSloBudgetBarFillPercent(
+        slo.errorBudgetRemainingPercentage,
+      ),
+      burnRate: formatSloBurnRate(slo.currentBurnRate),
+      burnRateTone: SloBurnRateTone.Unknown,
+      statusText: SLO_DISABLED_STATUS_LABEL,
+      statusColor: Gray500,
+    };
+  }
+
+  return {
+    sli: formatSloPercent(slo.currentSliPercentage, 3),
+    target: target === null ? null : `target ${target}`,
+    budget: formatSloPercent(slo.errorBudgetRemainingPercentage, 1),
+    budgetTime: formatErrorBudgetRemainingSeconds(
+      slo.errorBudgetRemainingSeconds,
+    ),
+    budgetFillPercent: getSloBudgetBarFillPercent(
+      slo.errorBudgetRemainingPercentage,
+    ),
+    burnRate: formatSloBurnRate(slo.currentBurnRate),
+    burnRateTone: getSloBurnRateTone(slo.currentBurnRate),
+    /*
+     * A NULL status is an SLO the worker has not reached yet. The single-SLO
+     * widget's pill says "Unknown"; in a list of objectives the summary strip
+     * counts it as not evaluated, so the row says the same thing.
+     */
+    statusText: slo.sloStatus
+      ? getSloStatusText(slo.sloStatus)
+      : SLO_NOT_EVALUATED_STATUS_LABEL,
+    statusColor: getSloStatusColor(slo.sloStatus),
+  };
+};
+
+export interface SloStatusSummaryEntry {
+  label: string;
+  count: number;
+  color: Color;
+}
+
+/*
+ * Severity order for the summary strip: what needs attention reads first.
+ * Paused and Misconfigured are not reliability signals, so they come after
+ * Healthy; Disabled follows them, and an SLO the worker has not evaluated yet
+ * comes last.
+ */
+const SUMMARY_ORDER: Array<{ status: SloStatus; color: Color }> = [
+  { status: SloStatus.BudgetExhausted, color: Red },
+  { status: SloStatus.AtRisk, color: Yellow },
+  { status: SloStatus.Healthy, color: Green },
+  { status: SloStatus.Misconfigured, color: Gray500 },
+  { status: SloStatus.Paused, color: Gray500 },
+];
+
+/*
+ * Counts per status for the rows the list is showing, worst first, omitting
+ * statuses nobody is in. A status string the enum does not know (a row
+ * written by a newer server) is counted as not evaluated rather than dropped,
+ * so the counts always add up to the number of rows.
+ *
+ * A disabled SLO is counted as Disabled whatever status it was frozen at, so
+ * an objective switched off while out of budget does not keep the strip
+ * reading "1 Budget Exhausted" for as long as it stays off — the same
+ * partition the SLOs page's summary tiles use.
+ */
+export type SummarizeSloStatusesFunction = (
+  slos: Array<SloListRowData>,
+) => Array<SloStatusSummaryEntry>;
+
+export const summarizeSloStatuses: SummarizeSloStatusesFunction = (
+  slos: Array<SloListRowData>,
+): Array<SloStatusSummaryEntry> => {
+  const counts: Map<string, number> = new Map<string, number>();
+  let notEvaluated: number = 0;
+  let disabled: number = 0;
+
+  const knownStatuses: Array<string> = SUMMARY_ORDER.map(
+    (entry: { status: SloStatus; color: Color }): string => {
+      return entry.status;
+    },
+  );
+
+  for (const slo of slos) {
+    if (isSloListRowDisabled(slo)) {
+      disabled++;
+      continue;
+    }
+
+    const status: string | undefined | null = slo.sloStatus;
+
+    if (!status || !knownStatuses.includes(status)) {
+      notEvaluated++;
+      continue;
+    }
+
+    counts.set(status, (counts.get(status) || 0) + 1);
+  }
+
+  const summary: Array<SloStatusSummaryEntry> = [];
+
+  for (const entry of SUMMARY_ORDER) {
+    const count: number = counts.get(entry.status) || 0;
+
+    if (count > 0) {
+      summary.push({ label: entry.status, count: count, color: entry.color });
+    }
+  }
+
+  if (disabled > 0) {
+    summary.push({
+      label: SLO_DISABLED_STATUS_LABEL,
+      count: disabled,
+      color: Gray500,
+    });
+  }
+
+  if (notEvaluated > 0) {
+    summary.push({
+      label: SLO_NOT_EVALUATED_STATUS_LABEL,
+      count: notEvaluated,
+      color: Gray500,
+    });
+  }
+
+  return summary;
+};
+
+/*
+ * The valid values of the widget's status filter, in the order the settings
+ * dropdown offers them. The public-dashboard policy validates stored filters
+ * against this same list.
+ */
+export const SLO_LIST_STATUS_FILTER_VALUES: Array<SloStatus> = [
+  SloStatus.BudgetExhausted,
+  SloStatus.AtRisk,
+  SloStatus.Healthy,
+  SloStatus.Misconfigured,
+  SloStatus.Paused,
+];