@oneuptime/common 12.0.14 → 12.0.15

package/Tests/Utils/NetworkDiscovery/UnclaimedScanDiagnosis.test.ts

@@ -0,0 +1,214 @@
+import {
+  MAX_SCAN_STATUS_MESSAGE_LENGTH,
+  UNCLAIMED_PENDING_MINUTES,
+  UnclaimedScanProbeState,
+  buildUnclaimedScanDiagnosis,
+} from "../../../Utils/NetworkDiscovery/UnclaimedScanDiagnosis";
+import OneUptimeDate from "../../../Types/Date";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * The sentence a stuck discovery scan gets to say for itself.
+ *
+ * A scan leaves "Pending" only when a probe asks for it. When no probe ever
+ * does, nothing times out and nothing fails — the row simply never moves, and
+ * before this existed the product said nothing at all about it. OneUptime
+ * issue #3287 is that silence: four scans submitted over an hour, all
+ * "Pending", an em-dash where the result goes, and no way to tell a scan
+ * queued a second ago from one no probe will ever pick up.
+ *
+ * So these tests are about the WORDS, not a state machine: whether an operator
+ * reading the row learns which of the two very different problems they have,
+ * and whether the sentence survives the varchar(500) column it is written to.
+ */
+
+const disconnectedProbe: UnclaimedScanProbeState = {
+  probeName: "Datacentre Probe",
+  isProbeConnected: false,
+  lastAliveAt: OneUptimeDate.getSomeHoursAgo(6),
+};
+
+const connectedProbe: UnclaimedScanProbeState = {
+  probeName: "Datacentre Probe",
+  isProbeConnected: true,
+  lastAliveAt: OneUptimeDate.getCurrentDate(),
+};
+
+describe("buildUnclaimedScanDiagnosis — the probe is not connected", () => {
+  test("names the probe the operator chose", () => {
+    expect(buildUnclaimedScanDiagnosis(disconnectedProbe)).toContain(
+      'Probe "Datacentre Probe"',
+    );
+  });
+
+  test("says the probe is not connected, which is the actual fault", () => {
+    expect(buildUnclaimedScanDiagnosis(disconnectedProbe)).toContain(
+      "is not connected to OneUptime",
+    );
+  });
+
+  /*
+   * "Last seen 6 hours ago" is the difference between "my probe just
+   * restarted" and "that probe has been gone since the upgrade".
+   */
+  test("says when the probe was last seen", () => {
+    expect(buildUnclaimedScanDiagnosis(disconnectedProbe)).toContain(
+      "It was last seen",
+    );
+  });
+
+  test("a probe that has never connected says exactly that, not 'last seen never'", () => {
+    const message: string = buildUnclaimedScanDiagnosis({
+      probeName: "Brand New Probe",
+      isProbeConnected: false,
+      lastAliveAt: null,
+    });
+
+    expect(message).toContain("It has never connected.");
+    expect(message).not.toContain("last seen");
+  });
+
+  test("a missing lastAlive is treated the same as never connecting", () => {
+    expect(
+      buildUnclaimedScanDiagnosis({
+        isProbeConnected: false,
+      }),
+    ).toContain("It has never connected.");
+  });
+
+  /*
+   * The scan is annotated, not failed, so the operator needs to know they do
+   * not have to re-create it.
+   */
+  test("promises the scan still runs once the probe returns", () => {
+    expect(buildUnclaimedScanDiagnosis(disconnectedProbe)).toContain(
+      "as soon as the probe reconnects",
+    );
+  });
+});
+
+describe("buildUnclaimedScanDiagnosis — the probe IS connected", () => {
+  /*
+   * A completely different problem with a completely different fix: the probe
+   * is running and authenticating, but its discovery job is not claiming
+   * scans — an old image, a wedged sweep, or a probe that can reach the
+   * heartbeat route but not the probe-ingest one.
+   */
+  test("does not blame the connection", () => {
+    const message: string = buildUnclaimedScanDiagnosis(connectedProbe);
+
+    expect(message).toContain("is connected but has not picked this scan up");
+    expect(message).not.toContain("is not connected");
+  });
+
+  test("names the two things worth checking", () => {
+    const message: string = buildUnclaimedScanDiagnosis(connectedProbe);
+
+    expect(message).toContain("version that supports");
+    expect(message).toContain("probe-ingest");
+  });
+
+  test("quotes the threshold it actually waited for", () => {
+    expect(buildUnclaimedScanDiagnosis(connectedProbe)).toContain(
+      `${UNCLAIMED_PENDING_MINUTES} minutes`,
+    );
+  });
+
+  test("the two branches are genuinely different sentences", () => {
+    expect(buildUnclaimedScanDiagnosis(connectedProbe)).not.toBe(
+      buildUnclaimedScanDiagnosis(disconnectedProbe),
+    );
+  });
+});
+
+describe("buildUnclaimedScanDiagnosis — a probe with no readable name", () => {
+  test("falls back to a phrase that still reads as a sentence", () => {
+    const message: string = buildUnclaimedScanDiagnosis({
+      isProbeConnected: false,
+      lastAliveAt: null,
+    });
+
+    expect(message).toContain("The assigned probe is not connected");
+    expect(message).not.toContain('Probe ""');
+  });
+
+  test("an empty-string name is treated as no name", () => {
+    expect(
+      buildUnclaimedScanDiagnosis({
+        probeName: "",
+        isProbeConnected: true,
+      }),
+    ).toContain("The assigned probe");
+  });
+});
+
+describe("buildUnclaimedScanDiagnosis — it has to fit the column", () => {
+  /*
+   * statusMessage is a varchar(500) and this message is written through the
+   * full update pipeline, which does NOT clamp. An over-long value throws, and
+   * the diagnosis is lost precisely when it is most needed.
+   */
+  test("the column ceiling is the one the model declares", () => {
+    expect(MAX_SCAN_STATUS_MESSAGE_LENGTH).toBe(500);
+  });
+
+  test("every message fits, for both branches", () => {
+    for (const probeState of [disconnectedProbe, connectedProbe]) {
+      expect(
+        buildUnclaimedScanDiagnosis(probeState).length,
+      ).toBeLessThanOrEqual(MAX_SCAN_STATUS_MESSAGE_LENGTH);
+    }
+  });
+
+  /*
+   * A probe name is a ShortText column, so 100 characters is the real worst
+   * case. Feeding well past it proves the truncation is what bounds the
+   * message rather than the caller's good manners.
+   */
+  test("an absurdly long probe name cannot overflow the column", () => {
+    const longName: string = "N".repeat(400);
+
+    for (const isProbeConnected of [true, false]) {
+      const message: string = buildUnclaimedScanDiagnosis({
+        probeName: longName,
+        isProbeConnected: isProbeConnected,
+        lastAliveAt: OneUptimeDate.getSomeHoursAgo(200),
+      });
+
+      expect(message.length).toBeLessThanOrEqual(
+        MAX_SCAN_STATUS_MESSAGE_LENGTH,
+      );
+    }
+  });
+
+  test("a long name is cut with an ellipsis rather than silently dropped", () => {
+    const message: string = buildUnclaimedScanDiagnosis({
+      probeName: "N".repeat(400),
+      isProbeConnected: false,
+    });
+
+    expect(message).toContain("NNN");
+    expect(message).toContain("…");
+  });
+
+  test("a name that fits is left exactly as the operator typed it", () => {
+    expect(
+      buildUnclaimedScanDiagnosis({
+        probeName: "core-sw-probe-01",
+        isProbeConnected: false,
+      }),
+    ).toContain('Probe "core-sw-probe-01"');
+  });
+});
+
+describe("the grace period", () => {
+  /*
+   * The probe polls every minute, so this is a count of consecutive failed
+   * polls. Too short and a probe redeploy annotates every queued scan; too
+   * long and the operator has given up before the product says anything.
+   */
+  test("is long enough to ride out a probe restart and short enough to be useful", () => {
+    expect(UNCLAIMED_PENDING_MINUTES).toBeGreaterThanOrEqual(5);
+    expect(UNCLAIMED_PENDING_MINUTES).toBeLessThanOrEqual(60);
+  });
+});

package/Types/Marketing/MarketingConversion.ts

@@ -1,8 +1,20 @@
 export enum MarketingConversionType {
   SignUp = "SignUp",
+  // A verified Cal.com booking. See Docs/analytics/enterprise-conversion-tracking.md.
+  MeetingBooked = "MeetingBooked",
   PaidSubscription = "PaidSubscription",
 }
 
+/*
+ * Conversion types that ad platforms have an explicit conversion-action
+ * mapping for. Every provider picks its platform conversion action by
+ * branching on SignUp vs not-SignUp, so a type that is not listed here would
+ * be uploaded as a purchase — add a type only once every provider has a
+ * mapping for it. Types left out stay ledger-only and are recorded as Skipped.
+ */
+export const AdUploadableMarketingConversionTypes: Array<MarketingConversionType> =
+  [MarketingConversionType.SignUp, MarketingConversionType.PaidSubscription];
+
 export enum MarketingConversionUploadStatus {
   Uploaded = "Uploaded",
   Failed = "Failed",

package/Types/Monitor/CriteriaFilter.ts

@@ -224,6 +224,14 @@ export enum EvaluateOverTimeMinutes {
 export interface EvaluateOverTimeOptions {
   timeValueInMinutes: number | undefined;
   evaluateOverTimeType: EvaluateOverTimeType | undefined;
+  /*
+   * Governs what happens when the evaluation window cannot back the filter -
+   * either nothing was recorded in it, or the monitor has not been running
+   * long enough to cover it yet. Defaults to Ignore when unset, so a filter
+   * asked to look at the last N minutes waits for N minutes of data instead
+   * of firing off the reading that happens to have just arrived.
+   */
+  onNoDataPolicy?: NoDataPolicy | undefined;
 }
 
 export interface CriteriaFilter {
@@ -449,5 +457,6 @@ export const CriteriaFilterSchema: ZodSchema = Zod.object({
   evaluateOverTimeOptions: Zod.object({
     timeValueInMinutes: Zod.number().optional(),
     evaluateOverTimeType: Zod.string().optional(),
+    onNoDataPolicy: Zod.string().optional(),
   }).optional(),
 });

package/Types/NetworkDevice/NetworkDeviceLinkRuleScope.ts

@@ -0,0 +1,51 @@
+/*
+ * How wide a link rule's "exactly one parent" question is asked.
+ *
+ * A rule says every device carrying ALL the child labels gets one uplink to
+ * the SINGLE device carrying ALL the parent labels. "Single" needs a universe,
+ * and until now that universe was whatever device set the topology query
+ * happened to hand the resolver. The same rule therefore resolved fine on a
+ * site-filtered map and collapsed to `ambiguousParent` on the global one —
+ * issue #3260, where fourteen units each have a router carrying
+ * `SubCategory:Router` and the global map drew NO rule uplinks at all, not
+ * even the thirteen unambiguous ones.
+ *
+ * Site asks the same question once per site instead. Opt-in, never inferred:
+ * inferring it would silently change what an already-saved rule draws, and a
+ * rule that quietly re-points cables is worse than one that refuses to draw.
+ *
+ * Stored as free text on the column (the NetworkDeviceMonitoringMethod
+ * precedent), so read it through `parse` rather than comparing the raw column:
+ * rows written before this existed hold NULL and must read as Project, which
+ * is what they are.
+ */
+export enum NetworkDeviceLinkRuleScope {
+  // One parent for the whole project. What every rule written so far means.
+  Project = "Project",
+  // One parent per site. Devices with no site are skipped, and said so.
+  Site = "Site",
+}
+
+export class NetworkDeviceLinkRuleScopeUtil {
+  /*
+   * NULL, empty, whitespace and anything unrecognised read as Project.
+   * Defaulting the other way would silently redraw somebody's map.
+   */
+  public static parse(
+    value: string | undefined | null,
+  ): NetworkDeviceLinkRuleScope {
+    if ((value || "").trim().toLowerCase() === "site") {
+      return NetworkDeviceLinkRuleScope.Site;
+    }
+    return NetworkDeviceLinkRuleScope.Project;
+  }
+
+  public static isSiteScoped(value: string | undefined | null): boolean {
+    return (
+      NetworkDeviceLinkRuleScopeUtil.parse(value) ===
+      NetworkDeviceLinkRuleScope.Site
+    );
+  }
+}
+
+export default NetworkDeviceLinkRuleScope;

package/UI/Components/FormModal/BasicFormModal.tsx

@@ -5,12 +5,19 @@ import ErrorMessage from "../ErrorMessage/ErrorMessage";
 import BasicForm, {
   BaseComponentProps as BasicFormComponentProps,
 } from "../Forms/BasicForm";
+import FormAnalyticsName from "../Forms/Utils/FormAnalyticsName";
 import Modal, { ModalWidth } from "../Modal/Modal";
 import GenericObject from "../../../Types/GenericObject";
 import React, { ReactElement, useEffect, useRef, useState } from "react";
 
 export interface ComponentProps<T extends GenericObject> {
   title: string;
+  /*
+   * Identifies this form in the "FORM SUBMIT" analytics event. Falls back to
+   * formProps.name and then to the modal title, so every modal reports a
+   * distinguishable conversion without each caller having to name it.
+   */
+  name?: string | undefined;
   isLoading?: boolean | undefined;
   error?: string | undefined;
   onClose?: undefined | (() => void);
@@ -51,6 +58,11 @@ const BasicFormModal: <T extends GenericObject>(
         {!isLoading && (
           <BasicForm
             {...props.formProps}
+            name={FormAnalyticsName.resolve(
+              props.name,
+              props.formProps.name,
+              props.title,
+            )}
             hideSubmitButton={true}
             ref={formRef}
             onLoadingChange={(isFormLoading: boolean) => {

package/UI/Components/Forms/BasicForm.tsx

@@ -20,6 +20,7 @@ import FormFieldSchemaType from "./Types/FormFieldSchemaType";
 import { FormStep } from "./Types/FormStep";
 import FormValues from "./Types/FormValues";
 import Validation from "./Validation";
+import FormAnalyticsName from "./Utils/FormAnalyticsName";
 import OneUptimeDate from "../../../Types/Date";
 import Dictionary from "../../../Types/Dictionary";
 import { VoidFunction } from "../../../Types/FunctionTypes";
@@ -447,7 +448,18 @@ const BasicForm: ForwardRefExoticComponent<any> = forwardRef(
           }
         }
 
-        UiAnalytics.capture("FORM SUBMIT: " + props.name);
+        const analyticsName: string | undefined = FormAnalyticsName.resolve(
+          props.name,
+        );
+
+        /*
+         * Unnamed forms are embedded sub-forms (filter builders, argument
+         * editors) rather than conversions. Skip them instead of reporting an
+         * event named after a missing prop.
+         */
+        if (analyticsName) {
+          UiAnalytics.capture("FORM SUBMIT: " + analyticsName);
+        }
 
         props.onSubmit(values, () => {
           setDidSomethingChange(false);

package/UI/Components/Forms/BasicModelForm.tsx

@@ -8,6 +8,7 @@ import BasicForm, {
 import Fields from "./Types/Fields";
 import { FormStep } from "./Types/FormStep";
 import FormValues from "./Types/FormValues";
+import FormAnalyticsName from "./Utils/FormAnalyticsName";
 import BaseModel from "../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
 import React, {
   MutableRefObject,
@@ -113,7 +114,7 @@ const BasicModelForm: <TBaseModel extends BaseModel>(
       onValidate={props.onValidate ? props.onValidate : DefaultValidateFunction}
       disableAutofocus={props.disableAutofocus}
       steps={props.steps}
-      name={props.name}
+      name={FormAnalyticsName.resolve(props.name, props.title)}
       onFormStepChange={props.onFormStepChange}
       submitButtonStyleType={props.submitButtonStyleType}
       onSubmit={props.onSubmit}

package/UI/Components/Forms/ModelForm.tsx

@@ -21,6 +21,7 @@ import Field from "./Types/Field";
 import Fields from "./Types/Fields";
 import { FormStep } from "./Types/FormStep";
 import FormValues from "./Types/FormValues";
+import FormAnalyticsName from "./Utils/FormAnalyticsName";
 import AnalyticsBaseModel from "../../../Models/AnalyticsModels/AnalyticsBaseModel/AnalyticsBaseModel";
 import AccessControlModel from "../../../Models/DatabaseModels/DatabaseBaseModel/AccessControlModel";
 import BaseModel from "../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
@@ -854,7 +855,15 @@ const ModelForm: <TBaseModel extends BaseModel>(
         disableAutofocus={props.disableAutofocus}
         model={model}
         id={props.id}
-        name={props.name}
+        name={FormAnalyticsName.resolve(
+          props.name,
+          props.title,
+          model.singularName
+            ? `${
+                props.formType === FormType.Create ? "Create" : "Update"
+              } ${model.singularName}`
+            : undefined,
+        )}
         onFormStepChange={props.onFormStepChange}
         onIsLastFormStep={props.onIsLastFormStep}
         fields={fields}

package/UI/Components/Forms/Utils/FormAnalyticsName.ts

@@ -0,0 +1,39 @@
+/*
+ * Matches "undefined" / "null" as a whole word, which is what a missing value
+ * turns into once it is interpolated into a title (`Duplicate ${undefined}`).
+ * Case sensitive on purpose: titles are written in Title Case, so a real word
+ * like "Null" in a form title is left alone.
+ */
+const STRINGIFIED_EMPTY_VALUE: RegExp = /\b(undefined|null)\b/;
+
+/*
+ * Resolves the human readable name that identifies a form in the
+ * "FORM SUBMIT" analytics event.
+ *
+ * Wrappers around BasicForm pass a chain of candidates - the explicit name
+ * first, then whatever title they already render - and the first usable one
+ * wins. When no candidate is usable the caller is expected to skip the capture
+ * altogether, because an event named after a missing value collapses distinct
+ * conversions into one indistinguishable event.
+ */
+export default class FormAnalyticsName {
+  public static resolve(
+    ...candidates: Array<string | undefined | null>
+  ): string | undefined {
+    for (const candidate of candidates) {
+      if (typeof candidate !== "string") {
+        continue;
+      }
+
+      const name: string = candidate.trim();
+
+      if (!name || STRINGIFIED_EMPTY_VALUE.test(name)) {
+        continue;
+      }
+
+      return name;
+    }
+
+    return undefined;
+  }
+}

package/UI/Components/ModelFormModal/ModelFormModal.tsx

@@ -7,6 +7,7 @@ import ModelForm, {
   ComponentProps as ModelFormComponentProps,
 } from "../Forms/ModelForm";
 import FormValues from "../Forms/Types/FormValues";
+import FormAnalyticsName from "../Forms/Utils/FormAnalyticsName";
 import Modal, { ModalWidth } from "../Modal/Modal";
 import BaseModel from "../../../Models/DatabaseModels/DatabaseBaseModel/DatabaseBaseModel";
 import { JSONObject } from "../../../Types/JSON";
@@ -77,7 +78,11 @@ const ModelFormModal: <TBaseModel extends BaseModel>(
         <>
           <ModelForm<TBaseModel>
             {...props.formProps}
-            name={props.name}
+            name={FormAnalyticsName.resolve(
+              props.name,
+              props.formProps.name,
+              props.title,
+            )}
             modelAPI={props.modelAPI}
             modelType={props.modelType}
             onIsLastFormStep={(isLastFormStep: boolean) => {

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/Monitor/MonitorMetricType.ts

@@ -95,6 +95,46 @@ class MonitorMetricTypeUtil {
     }
   }
 
+  /**
+   * Metric series that backs this CheckOn, or null when nothing records it.
+   *
+   * The throwing variant below is kept for callers that genuinely cannot
+   * continue without a series. Over-time evaluation needs the null instead:
+   * it used to call the throwing one inside a try/catch that swallowed the
+   * error and quietly compared the instantaneous value, so "evaluate over
+   * time" was a no-op for every CheckOn missing from this map - DNS, SNMP
+   * and External Status Page checks among them.
+   */
+  public static getMonitorMetricTypeByCheckOnOrNull(
+    checkOn: CheckOn,
+  ): MonitorMetricType | null {
+    switch (checkOn) {
+      /*
+       * DNS / SNMP / External Status Page probes write into the shared
+       * online and response-time series like every other probe check, so
+       * their CheckOns map onto those series rather than onto ones of their
+       * own.
+       */
+      case CheckOn.DnsIsOnline:
+      case CheckOn.SnmpIsOnline:
+      case CheckOn.ExternalStatusPageIsOnline:
+        return MonitorMetricType.IsOnline;
+      case CheckOn.DnsResponseTime:
+      case CheckOn.SnmpResponseTime:
+      case CheckOn.ExternalStatusPageResponseTime:
+        return MonitorMetricType.ResponseTime;
+      default:
+        break;
+    }
+
+    try {
+      return this.getMonitorMeticTypeByCheckOn(checkOn);
+    } catch {
+      // No series records this CheckOn.
+      return null;
+    }
+  }
+
   public static getMonitorMeticTypeByCheckOn(
     checkOn: CheckOn,
   ): MonitorMetricType {