@oneuptime/common 12.0.14 → 12.0.16

package/Utils/Analytics.ts

@@ -7,6 +7,18 @@ import {
   RevenueEventProperties,
 } from "../Types/Analytics/RevenueEvent";
 
+// GA4 rejects event names longer than 40 characters.
+const GA4_MAX_EVENT_NAME_LENGTH: number = 40;
+
+/*
+ * Prefix used when a name has no usable leading letter (GA4 requires the first
+ * character to be a letter, so names like "404_page" cannot be sent as-is).
+ */
+const GA4_EVENT_NAME_FALLBACK: string = "event";
+
+// GA4 requires the first character of an event name to be a letter.
+const GA4_EVENT_NAME_LEADING_LETTER: RegExp = /^[a-z]/;
+
 export default class Analytics {
   private _isInitialized: boolean = false;
   public get isInitialized(): boolean {
@@ -47,8 +59,44 @@ export default class Analytics {
     });
   }
 
+  /**
+   * Coerce an arbitrary event name into one GA4 accepts: it must start with a
+   * letter and contain only letters, digits and underscores, up to 40
+   * characters.
+   *
+   * Product code calls capture() with free-form, human-readable names
+   * ("Page View: Project > Home", "FORM SUBMIT: Register", "accounts/login"),
+   * which GA4 would reject. Every name in RevenueEventName is already
+   * compliant and passes through unchanged, so GTM tags keyed on those names
+   * are unaffected.
+   *
+   * This is deliberately applied to the dataLayer branch only — the name sent
+   * to PostHog is left untouched so existing PostHog insights and dashboards
+   * keep matching.
+   */
+  public static toGA4EventName(eventName: string): string {
+    let name: string = eventName
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "_")
+      .replace(/^_+|_+$/g, "");
+
+    if (name.length === 0) {
+      return GA4_EVENT_NAME_FALLBACK;
+    }
+
+    if (!GA4_EVENT_NAME_LEADING_LETTER.test(name)) {
+      name = `${GA4_EVENT_NAME_FALLBACK}_${name}`;
+    }
+
+    /*
+     * Truncating can leave a trailing underscore. The name starts with a
+     * letter by this point, so stripping those always leaves a valid name.
+     */
+    return name.slice(0, GA4_MAX_EVENT_NAME_LENGTH).replace(/_+$/g, "");
+  }
+
   public capture(eventName: string, data?: JSONObject): void {
-    // PostHog tracking
+    // PostHog tracking. The original, un-normalised name is used here.
     if (this.isInitialized) {
       posthog.capture(eventName, data);
     }
@@ -60,10 +108,15 @@ export default class Analytics {
      */
     if (typeof window !== "undefined" && (window as any).dataLayer) {
       (window as any).dataLayer.push({
-        event: eventName,
         eventCategory: "analytics",
+        // The raw name is kept here so the original is still readable in GTM.
         eventAction: eventName,
         ...(data || {}),
+        /*
+         * `event` is the GA4 event name and has to stay valid, so it is
+         * applied after the spread and cannot be overridden by properties.
+         */
+        event: Analytics.toGA4EventName(eventName),
       });
     }
   }

package/Utils/Dashboard/Components/DashboardSecurityEventsFlowComponent.ts

@@ -0,0 +1,84 @@
+import DashboardSecurityEventsFlowComponent from "../../../Types/Dashboard/DashboardComponents/DashboardSecurityEventsFlowComponent";
+import { ObjectType } from "../../../Types/JSON";
+import ObjectID from "../../../Types/ObjectID";
+import OcsfSeverity from "../../../Types/SecurityEvent/OcsfSeverity";
+import DashboardBaseComponentUtil from "./DashboardBaseComponent";
+import {
+  ComponentArgument,
+  ComponentArgumentSection,
+  ComponentInputType,
+} from "../../../Types/Dashboard/DashboardComponents/ComponentArgument";
+import DashboardComponentType from "../../../Types/Dashboard/DashboardComponentType";
+import { DropdownOption } from "../../../UI/Components/Dropdown/Dropdown";
+
+const DisplaySection: ComponentArgumentSection = {
+  name: "Display Options",
+  description: "Configure the flow heading",
+  order: 1,
+};
+
+const FiltersSection: ComponentArgumentSection = {
+  name: "Filters",
+  description: "Choose which security events contribute to the flow",
+  order: 2,
+  defaultCollapsed: true,
+};
+
+export default class DashboardSecurityEventsFlowComponentUtil extends DashboardBaseComponentUtil {
+  public static override getDefaultComponent(): DashboardSecurityEventsFlowComponent {
+    return {
+      _type: ObjectType.DashboardComponent,
+      componentType: DashboardComponentType.SecurityEventsFlow,
+      widthInDashboardUnits: 8,
+      heightInDashboardUnits: 5,
+      topInDashboardUnits: 0,
+      leftInDashboardUnits: 0,
+      componentId: ObjectID.generate(),
+      minHeightInDashboardUnits: 4,
+      minWidthInDashboardUnits: 6,
+      arguments: {
+        maxEvents: 500,
+      },
+    };
+  }
+
+  public static override getComponentConfigArguments(): Array<
+    ComponentArgument<DashboardSecurityEventsFlowComponent>
+  > {
+    return [
+      {
+        name: "Title",
+        description: "Header shown above the security events flow",
+        required: false,
+        type: ComponentInputType.Text,
+        id: "title",
+        placeholder: "Security Events Flow",
+        section: DisplaySection,
+      },
+      {
+        name: "Severities",
+        description: "Only include events at the selected OCSF severity levels",
+        required: false,
+        type: ComponentInputType.MultiSelectDropdown,
+        id: "severityFilters",
+        placeholder: "All severities",
+        section: FiltersSection,
+        dropdownOptions: Object.values(OcsfSeverity).map(
+          (severity: OcsfSeverity): DropdownOption => {
+            return { label: severity, value: severity };
+          },
+        ),
+      },
+      {
+        name: "Max Events",
+        description:
+          "How many of the most recent events to build the flow from (up to 1000)",
+        required: false,
+        type: ComponentInputType.Number,
+        id: "maxEvents",
+        placeholder: "500",
+        section: FiltersSection,
+      },
+    ];
+  }
+}

package/Utils/Dashboard/Components/DashboardSecurityEventsListComponent.ts

@@ -0,0 +1,110 @@
+import DashboardSecurityEventsListComponent from "../../../Types/Dashboard/DashboardComponents/DashboardSecurityEventsListComponent";
+import { ObjectType } from "../../../Types/JSON";
+import ObjectID from "../../../Types/ObjectID";
+import OcsfSeverity from "../../../Types/SecurityEvent/OcsfSeverity";
+import {
+  OcsfEventClasses,
+  OcsfEventClassProps,
+} from "../../../Types/SecurityEvent/OcsfEventClass";
+import DashboardBaseComponentUtil from "./DashboardBaseComponent";
+import {
+  ComponentArgument,
+  ComponentArgumentSection,
+  ComponentInputType,
+} from "../../../Types/Dashboard/DashboardComponents/ComponentArgument";
+import DashboardComponentType from "../../../Types/Dashboard/DashboardComponentType";
+import { DropdownOption } from "../../../UI/Components/Dropdown/Dropdown";
+
+const DisplaySection: ComponentArgumentSection = {
+  name: "Display Options",
+  description: "Configure the widget title and row limit",
+  order: 1,
+};
+
+const FiltersSection: ComponentArgumentSection = {
+  name: "Filters",
+  description: "Narrow down which security events are shown",
+  order: 2,
+  defaultCollapsed: true,
+};
+
+export default class DashboardSecurityEventsListComponentUtil extends DashboardBaseComponentUtil {
+  public static override getDefaultComponent(): DashboardSecurityEventsListComponent {
+    return {
+      _type: ObjectType.DashboardComponent,
+      componentType: DashboardComponentType.SecurityEventsList,
+      widthInDashboardUnits: 8,
+      heightInDashboardUnits: 5,
+      topInDashboardUnits: 0,
+      leftInDashboardUnits: 0,
+      componentId: ObjectID.generate(),
+      minHeightInDashboardUnits: 3,
+      minWidthInDashboardUnits: 6,
+      arguments: {
+        limit: 10,
+      },
+    };
+  }
+
+  public static override getComponentConfigArguments(): Array<
+    ComponentArgument<DashboardSecurityEventsListComponent>
+  > {
+    return [
+      {
+        name: "Title",
+        description: "Header shown above the security events list",
+        required: false,
+        type: ComponentInputType.Text,
+        id: "title",
+        placeholder: "Security Events",
+        section: DisplaySection,
+      },
+      {
+        name: "Limit",
+        description: "Maximum number of security events to show (up to 50)",
+        required: false,
+        type: ComponentInputType.Number,
+        id: "limit",
+        placeholder: "10",
+        section: DisplaySection,
+      },
+      {
+        name: "Severities",
+        description: "Only show events at the selected OCSF severity levels",
+        required: false,
+        type: ComponentInputType.MultiSelectDropdown,
+        id: "severityFilters",
+        placeholder: "All severities",
+        section: FiltersSection,
+        dropdownOptions: Object.values(OcsfSeverity).map(
+          (severity: OcsfSeverity): DropdownOption => {
+            return { label: severity, value: severity };
+          },
+        ),
+      },
+      {
+        name: "Event Classes",
+        description: "Only show events of the selected OCSF event classes",
+        required: false,
+        type: ComponentInputType.MultiSelectDropdown,
+        id: "classNameFilters",
+        placeholder: "All event classes",
+        section: FiltersSection,
+        dropdownOptions: OcsfEventClasses.map(
+          (eventClass: OcsfEventClassProps): DropdownOption => {
+            return { label: eventClass.name, value: eventClass.name };
+          },
+        ),
+      },
+      {
+        name: "Message Contains",
+        description: "Only show events whose message contains this text",
+        required: false,
+        type: ComponentInputType.Text,
+        id: "messageContains",
+        placeholder: "Search text...",
+        section: FiltersSection,
+      },
+    ];
+  }
+}

package/Utils/Dashboard/Components/Index.ts

@@ -38,6 +38,8 @@ import DashboardPodmanImageListComponentUtil from "./DashboardPodmanImageListCom
 import DashboardPodmanNetworkListComponentUtil from "./DashboardPodmanNetworkListComponent";
 import DashboardPodmanVolumeListComponentUtil from "./DashboardPodmanVolumeListComponent";
 import DashboardProxmoxGuestListComponentUtil from "./DashboardProxmoxGuestListComponent";
+import DashboardSecurityEventsFlowComponentUtil from "./DashboardSecurityEventsFlowComponent";
+import DashboardSecurityEventsListComponentUtil from "./DashboardSecurityEventsListComponent";
 import DashboardSloComponentUtil from "./DashboardSloComponent";
 import DashboardProxmoxNodeListComponentUtil from "./DashboardProxmoxNodeListComponent";
 import DashboardDockerSwarmNodeListComponentUtil from "./DashboardDockerSwarmNodeListComponent";
@@ -125,6 +127,18 @@ export default class DashboardComponentsUtil {
       >;
     }
 
+    if (dashboardComponentType === DashboardComponentType.SecurityEventsList) {
+      return DashboardSecurityEventsListComponentUtil.getComponentConfigArguments() as Array<
+        ComponentArgument<DashboardBaseComponent>
+      >;
+    }
+
+    if (dashboardComponentType === DashboardComponentType.SecurityEventsFlow) {
+      return DashboardSecurityEventsFlowComponentUtil.getComponentConfigArguments() as Array<
+        ComponentArgument<DashboardBaseComponent>
+      >;
+    }
+
     if (dashboardComponentType === DashboardComponentType.TraceList) {
       return DashboardTraceListComponentUtil.getComponentConfigArguments() as Array<
         ComponentArgument<DashboardBaseComponent>

package/Utils/Measurement/MeasurementEvaluator.ts

@@ -0,0 +1,359 @@
+import MeasurementAnchorKind from "../../Types/Measurement/MeasurementAnchorKind";
+import MeasurementOccurrence from "../../Types/Measurement/MeasurementOccurrence";
+import MeasurementStatus from "../../Types/Measurement/MeasurementStatus";
+import OneUptimeDate from "../../Types/Date";
+
+/*
+ * One row of an entity's state timeline, flattened to the fields a
+ * measurement cares about. Domain services map IncidentStateTimeline,
+ * AlertStateTimeline or ScheduledMaintenanceStateTimeline onto this.
+ */
+export interface MeasurementTimelineEntry {
+  id: string;
+  stateId: string;
+  stateName?: string | undefined;
+  /*
+   * The state's position in the project's ordered state list. Used only to
+   * decide whether an unreached state can still be reached -- the timeline
+   * services enforce strictly increasing order, so a state at or below the
+   * current position will never be entered again.
+   */
+  stateOrder?: number | undefined;
+  // Role flags this state carries, e.g. ["Acknowledged"].
+  stateRoles?: Array<string> | undefined;
+  startsAt: Date;
+}
+
+export interface MeasurementAnchorSpec {
+  kind: MeasurementAnchorKind;
+
+  // Human-readable name of this endpoint, used verbatim in status messages.
+  label: string;
+
+  // Kind === Timestamp: the already-resolved value, or undefined if unset.
+  timestamp?: Date | undefined;
+
+  // Kind === StateEntered.
+  stateId?: string | undefined;
+  stateOrder?: number | undefined;
+
+  // Kind === StateRoleEntered.
+  stateRole?: string | undefined;
+
+  occurrence?: MeasurementOccurrence | undefined;
+
+  /*
+   * True when the definition references a state that has since been deleted.
+   * The FK is SET NULL rather than RESTRICT so that deleting a state never
+   * blocks a project from reordering its states; the measurement degrades to
+   * NotApplicable and says so instead of throwing.
+   */
+  isDanglingStateReference?: boolean | undefined;
+
+  /*
+   * Timestamp anchors that legitimately land after the entity reaches a
+   * terminal state -- a postmortem is posted after resolution -- must stay
+   * Pending rather than being declared unreachable.
+   */
+  canResolveAfterTerminalState?: boolean | undefined;
+}
+
+export interface MeasurementDefinitionSpec {
+  id: string;
+  name: string;
+  start: MeasurementAnchorSpec;
+  end: MeasurementAnchorSpec;
+}
+
+export interface EvaluatedMeasurement {
+  measurementId: string;
+  status: MeasurementStatus;
+  statusMessage?: string | undefined;
+  startedAt?: Date | undefined;
+  endedAt?: Date | undefined;
+  valueInSeconds?: number | undefined;
+  startTimelineEntryId?: string | undefined;
+  endTimelineEntryId?: string | undefined;
+}
+
+interface ResolvedAnchor {
+  at?: Date | undefined;
+  timelineEntryId?: string | undefined;
+  status: MeasurementStatus;
+  statusMessage?: string | undefined;
+}
+
+/*
+ * Evaluates measurement definitions against an entity's timeline.
+ *
+ * Two properties make this correct where the previous hand-rolled metric
+ * blocks were not:
+ *
+ *   1. It is a TOTAL FUNCTION of the data it is handed. It never reads its
+ *      own prior output, so a backdated timestamp, a deleted timeline row, a
+ *      state id edited through the API or a duplicated state all converge on
+ *      the right answer with no per-case handling and no repair path.
+ *
+ *   2. It is PURE -- no I/O, no clock, no database. The same function serves
+ *      the server-side recompute and can be run in the browser over a
+ *      timeline the page has already fetched, so a rendered number and a
+ *      stored number can never disagree.
+ */
+export default class MeasurementEvaluator {
+  public static evaluate(data: {
+    definitions: Array<MeasurementDefinitionSpec>;
+    timeline: Array<MeasurementTimelineEntry>;
+  }): Array<EvaluatedMeasurement> {
+    const timeline: Array<MeasurementTimelineEntry> =
+      MeasurementEvaluator.sortTimeline(data.timeline);
+
+    return data.definitions.map((definition: MeasurementDefinitionSpec) => {
+      return MeasurementEvaluator.evaluateOne({
+        definition: definition,
+        timeline: timeline,
+      });
+    });
+  }
+
+  public static evaluateOne(data: {
+    definition: MeasurementDefinitionSpec;
+    timeline: Array<MeasurementTimelineEntry>;
+  }): EvaluatedMeasurement {
+    const { definition } = data;
+    const timeline: Array<MeasurementTimelineEntry> = data.timeline;
+
+    const start: ResolvedAnchor = MeasurementEvaluator.resolveAnchor({
+      anchor: definition.start,
+      timeline: timeline,
+    });
+
+    const end: ResolvedAnchor = MeasurementEvaluator.resolveAnchor({
+      anchor: definition.end,
+      timeline: timeline,
+    });
+
+    /*
+     * NotApplicable outranks Pending: if one end can never resolve, the
+     * measurement can never complete, however much of it is still in flight.
+     */
+    const unresolved: Array<ResolvedAnchor> = [start, end].filter(
+      (anchor: ResolvedAnchor) => {
+        return !anchor.at;
+      },
+    );
+
+    if (unresolved.length > 0) {
+      const notApplicable: ResolvedAnchor | undefined = unresolved.find(
+        (anchor: ResolvedAnchor) => {
+          return anchor.status === MeasurementStatus.NotApplicable;
+        },
+      );
+
+      const chosen: ResolvedAnchor = notApplicable || unresolved[0]!;
+
+      return {
+        measurementId: definition.id,
+        status: chosen.status,
+        statusMessage: chosen.statusMessage,
+        startedAt: start.at,
+        endedAt: end.at,
+        startTimelineEntryId: start.timelineEntryId,
+        endTimelineEntryId: end.timelineEntryId,
+      };
+    }
+
+    const startMs: number = OneUptimeDate.fromString(start.at!).getTime();
+    const endMs: number = OneUptimeDate.fromString(end.at!).getTime();
+
+    if (endMs < startMs) {
+      /*
+       * The end really did land before the start. Reporting Invalid rather
+       * than clamping to zero is the entire point: a recorded timestamp is
+       * wrong and somebody needs to see it.
+       */
+      return {
+        measurementId: definition.id,
+        status: MeasurementStatus.Invalid,
+        statusMessage: `${definition.end.label} precedes ${
+          definition.start.label
+        } by ${MeasurementEvaluator.formatDuration(
+          Math.round((startMs - endMs) / 1000),
+        )}`,
+        startedAt: start.at,
+        endedAt: end.at,
+        startTimelineEntryId: start.timelineEntryId,
+        endTimelineEntryId: end.timelineEntryId,
+      };
+    }
+
+    return {
+      measurementId: definition.id,
+      status: MeasurementStatus.Recorded,
+      startedAt: start.at,
+      endedAt: end.at,
+      valueInSeconds: Math.round((endMs - startMs) / 1000),
+      startTimelineEntryId: start.timelineEntryId,
+      endTimelineEntryId: end.timelineEntryId,
+    };
+  }
+
+  /*
+   * startsAt alone is not a total order -- the timeline tables carry no
+   * unique constraint and an operator correcting timestamps can produce
+   * ties -- so the row id breaks them. Without this, "first occurrence"
+   * could differ between two queries over identical data.
+   */
+  public static sortTimeline(
+    timeline: Array<MeasurementTimelineEntry>,
+  ): Array<MeasurementTimelineEntry> {
+    return [...timeline].sort(
+      (a: MeasurementTimelineEntry, b: MeasurementTimelineEntry) => {
+        const aMs: number = OneUptimeDate.fromString(a.startsAt).getTime();
+        const bMs: number = OneUptimeDate.fromString(b.startsAt).getTime();
+
+        if (aMs !== bMs) {
+          return aMs - bMs;
+        }
+
+        return a.id.localeCompare(b.id);
+      },
+    );
+  }
+
+  private static resolveAnchor(data: {
+    anchor: MeasurementAnchorSpec;
+    timeline: Array<MeasurementTimelineEntry>;
+  }): ResolvedAnchor {
+    const { anchor, timeline } = data;
+
+    if (anchor.isDanglingStateReference) {
+      return {
+        status: MeasurementStatus.NotApplicable,
+        statusMessage: `The state this measurement's "${anchor.label}" pointed at has been deleted`,
+      };
+    }
+
+    if (anchor.kind === MeasurementAnchorKind.Timestamp) {
+      if (anchor.timestamp) {
+        return { at: anchor.timestamp, status: MeasurementStatus.Recorded };
+      }
+
+      /*
+       * A timestamp that is filled in later (a postmortem, an
+       * operator-recorded impact start) is still coming. One that is only
+       * ever written at creation and is missing never will be.
+       */
+      if (anchor.canResolveAfterTerminalState) {
+        return {
+          status: MeasurementStatus.Pending,
+          statusMessage: `${anchor.label} has not been recorded yet`,
+        };
+      }
+
+      return {
+        status: MeasurementStatus.NotApplicable,
+        statusMessage: `${anchor.label} was never recorded`,
+      };
+    }
+
+    const matches: Array<MeasurementTimelineEntry> = timeline.filter(
+      (entry: MeasurementTimelineEntry) => {
+        if (anchor.kind === MeasurementAnchorKind.StateEntered) {
+          return entry.stateId === anchor.stateId;
+        }
+
+        return (entry.stateRoles || []).includes(anchor.stateRole || "");
+      },
+    );
+
+    if (matches.length > 0) {
+      const entry: MeasurementTimelineEntry =
+        anchor.occurrence === MeasurementOccurrence.Last
+          ? matches[matches.length - 1]!
+          : matches[0]!;
+
+      return {
+        at: entry.startsAt,
+        timelineEntryId: entry.id,
+        status: MeasurementStatus.Recorded,
+      };
+    }
+
+    if (
+      MeasurementEvaluator.isStateStillReachable({
+        anchor: anchor,
+        timeline: timeline,
+      })
+    ) {
+      return {
+        status: MeasurementStatus.Pending,
+        statusMessage: `${anchor.label} has not been reached yet`,
+      };
+    }
+
+    return {
+      status: MeasurementStatus.NotApplicable,
+      statusMessage: `${anchor.label} was skipped`,
+    };
+  }
+
+  /*
+   * A state anchor is unreachable once the entity has moved past it.
+   *
+   * The order comparison -- rather than "is the entity resolved?" -- is what
+   * makes this exact. Projects are encouraged to add states after Resolved,
+   * so keying on a resolved flag would wrongly declare those unreachable,
+   * and keying on nothing would leave a skipped state Pending forever.
+   */
+  private static isStateStillReachable(data: {
+    anchor: MeasurementAnchorSpec;
+    timeline: Array<MeasurementTimelineEntry>;
+  }): boolean {
+    const { anchor, timeline } = data;
+
+    if (timeline.length === 0) {
+      // Nothing has happened yet, so everything is still ahead.
+      return true;
+    }
+
+    /*
+     * A role anchor has no single order to compare against -- any number of
+     * states may carry the role, and a project may have none at all. Leaving
+     * it Pending is the honest answer: nothing rules it out.
+     */
+    if (anchor.kind === MeasurementAnchorKind.StateRoleEntered) {
+      return true;
+    }
+
+    const currentOrder: number | undefined =
+      timeline[timeline.length - 1]!.stateOrder;
+
+    if (currentOrder === undefined || anchor.stateOrder === undefined) {
+      return true;
+    }
+
+    return currentOrder < anchor.stateOrder;
+  }
+
+  public static formatDuration(seconds: number): string {
+    if (seconds < 60) {
+      return `${seconds}s`;
+    }
+
+    const minutes: number = Math.floor(seconds / 60);
+
+    if (minutes < 60) {
+      return `${minutes}m`;
+    }
+
+    const hours: number = Math.floor(minutes / 60);
+
+    if (hours < 24) {
+      return minutes % 60 === 0 ? `${hours}h` : `${hours}h ${minutes % 60}m`;
+    }
+
+    const days: number = Math.floor(hours / 24);
+
+    return hours % 24 === 0 ? `${days}d` : `${days}d ${hours % 24}h`;
+  }
+}