@oneuptime/common 14.0.9 → 14.0.11

package/Tests/Types/Monitor/MetricEngineFold.ts

@@ -0,0 +1,154 @@
+import { MetricService } from "../../../Server/Services/MetricService";
+import AggregationType from "../../../Types/BaseDatabase/AggregationType";
+import MetricsAggregationType from "../../../Types/Metrics/MetricsAggregationType";
+
+/*
+ * The metric engine's folds, modelled: what one one-minute bucket of stored
+ * Metric rows aggregates to, for each scalar aggregation a metric monitor
+ * query can ask for.
+ *
+ * MessageQueueAlertTemplates.test evaluates the queue alert templates over
+ * broker-shaped rows through engineFold, and pins the SQL it ports
+ * (engineExpression) verbatim. Whether that SQL computes what engineFold
+ * says is a question only a real ClickHouse server answers, so the App
+ * suite Tests/Workers/Jobs/TelemetryMonitor/MetricEngineFoldClickhouse.test
+ * runs it there: the App Test workflow provides the server (Common's does
+ * not) and fails the run if it ever goes missing.
+ */
+
+/*
+ * One stored Metric row, as far as a fold reads it: `value`, and for a
+ * distribution point (a histogram or a summary: `count` set) its count,
+ * sum, min and max. A CloudWatch point is a Summary — count = SampleCount,
+ * sum = Sum (mirrored into value) — with no min or max column, because a
+ * Summary proto carries none (OtelMetricsIngestService reads the point's
+ * `min` / `max`, which only a histogram has).
+ */
+export interface StoredPoint {
+  value: number | null;
+  count?: number | null | undefined;
+  sum?: number | null | undefined;
+  min?: number | null | undefined;
+  max?: number | null | undefined;
+}
+
+export function isPresent(value: number | null | undefined): value is number {
+  return value !== null && value !== undefined;
+}
+
+/*
+ * How the metric engine folds one bucket of rows for a scalar aggregation:
+ * a port of MetricService.getDistributionAwareAggregationExpression, which
+ * every template query compiles to (its attribute filter keeps it off the
+ * rollups).
+ */
+export function engineFold(
+  points: Array<StoredPoint>,
+  aggregationType: MetricsAggregationType,
+): number | null {
+  const observationTotal: (point: StoredPoint) => number | null = (
+    point: StoredPoint,
+  ): number | null => {
+    return isPresent(point.sum) ? point.sum : point.value;
+  };
+  const isDistribution: (point: StoredPoint) => boolean = (
+    point: StoredPoint,
+  ): boolean => {
+    return isPresent(point.count) && isPresent(observationTotal(point));
+  };
+  const bound: (
+    point: StoredPoint,
+    stored: number | null | undefined,
+  ) => number | null = (
+    point: StoredPoint,
+    stored: number | null | undefined,
+  ): number | null => {
+    if (isPresent(stored)) {
+      return stored;
+    }
+    if (isDistribution(point) && point.count! > 0) {
+      return observationTotal(point)! / point.count!;
+    }
+    return isPresent(point.value) ? point.value : null;
+  };
+
+  let total: number = 0;
+  let observations: number = 0;
+
+  for (const point of points) {
+    if (isDistribution(point)) {
+      total += observationTotal(point)!;
+      observations += point.count!;
+    } else if (isPresent(point.value)) {
+      total += point.value;
+      observations += 1;
+    }
+  }
+
+  const bounds: (
+    pick: (point: StoredPoint) => number | null,
+  ) => Array<number> = (
+    pick: (point: StoredPoint) => number | null,
+  ): Array<number> => {
+    return points
+      .map((point: StoredPoint): number | null => {
+        return pick(point);
+      })
+      .filter((value: number | null): value is number => {
+        return value !== null;
+      });
+  };
+
+  switch (aggregationType) {
+    case MetricsAggregationType.Sum:
+      return total;
+    case MetricsAggregationType.Count:
+      return observations;
+    case MetricsAggregationType.Avg:
+      return observations === 0 ? 0 : total / observations;
+    case MetricsAggregationType.Min: {
+      const values: Array<number> = bounds(
+        (point: StoredPoint): number | null => {
+          return bound(point, point.min);
+        },
+      );
+      return values.length > 0 ? Math.min(...values) : null;
+    }
+    case MetricsAggregationType.Max: {
+      const values: Array<number> = bounds(
+        (point: StoredPoint): number | null => {
+          return bound(point, point.max);
+        },
+      );
+      return values.length > 0 ? Math.max(...values) : null;
+    }
+    default:
+      throw new Error(`No engine fold for ${aggregationType}`);
+  }
+}
+
+// Every aggregation engineFold ports.
+export const ENGINE_FOLD_AGGREGATIONS: ReadonlyArray<MetricsAggregationType> = [
+  MetricsAggregationType.Sum,
+  MetricsAggregationType.Count,
+  MetricsAggregationType.Avg,
+  MetricsAggregationType.Min,
+  MetricsAggregationType.Max,
+];
+
+// The engine the telemetry worker asks for a metric monitor's aggregates.
+export const METRIC_ENGINE: MetricService = new MetricService();
+
+// The SQL fold the engine compiles a scalar aggregation over `value` to.
+export function engineExpression(
+  aggregationType: MetricsAggregationType,
+): string {
+  return (
+    METRIC_ENGINE as unknown as {
+      getDistributionAwareAggregationExpression: (
+        aggregationType: AggregationType,
+        column: string,
+      ) => string;
+    }
+  ).getDistributionAwareAggregationExpression(aggregationType, "value");
+}

package/Tests/Types/Monitor/Recommendation/MonitorRecommendationCatalog.test.ts

@@ -19,7 +19,11 @@ import { getAllIoTAlertTemplates } from "../../../../Types/Monitor/IotAlertTempl
 import { getAllKubernetesAlertTemplates } from "../../../../Types/Monitor/KubernetesAlertTemplates";
 import { getAllPodmanAlertTemplates } from "../../../../Types/Monitor/PodmanAlertTemplates";
 import { getAllProxmoxAlertTemplates } from "../../../../Types/Monitor/ProxmoxAlertTemplates";
-import { getAllRumAlertTemplates } from "../../../../Types/Monitor/RumAlertTemplates";
+import {
+  RumAlertTemplate,
+  getAllRumAlertTemplates,
+  getRumAlertTemplates,
+} from "../../../../Types/Monitor/RumAlertTemplates";
 import { getAllVMwareAlertTemplates } from "../../../../Types/Monitor/VMwareAlertTemplates";
 import {
   getAllServiceAlertTemplates,
@@ -69,16 +73,18 @@ interface ModuleExpectation {
   resourceType: MonitorRecommendationResourceType;
   monitorTypes: Array<MonitorType>;
   /*
-   * Everything the module can ever produce. For nine of the ten this is also
-   * what the page shows; for Service it is the union across every runtime.
+   * Everything the module can ever produce. For the resource types whose set
+   * is a constant this is also what the page shows; for Service it is the
+   * union across every runtime, for Database across every engine, and for RUM
+   * it includes the session replay budget alerts.
    */
   templateCount: number;
   /*
    * What `getRecommendations(resourceType)` returns with NO context — what a
    * caller that knows nothing about the specific resource is offered. Equal to
    * `templateCount` for every resource type whose set is a constant, and
-   * smaller for Service, where knowing nothing means the language-agnostic
-   * subset.
+   * smaller for Service (the language-agnostic subset), Database (nothing)
+   * and RUM (everything but the budget alerts).
    */
   contextFreeTemplateCount: number;
   identifierFieldName:
@@ -163,7 +169,13 @@ const MODULE_EXPECTATIONS: Array<ModuleExpectation> = [
       MonitorType.Exceptions,
     ],
     templateCount: getAllRumAlertTemplates().length,
-    contextFreeTemplateCount: getAllRumAlertTemplates().length,
+    /*
+     * Everything but the session replay budget alerts, which wait until the
+     * application is known to record replays. `getRumAlertTemplates(undefined)`
+     * is the module's own answer to "what applies to an application we know
+     * nothing about".
+     */
+    contextFreeTemplateCount: getRumAlertTemplates(undefined).length,
     identifierFieldName: "rumApplicationId",
   },
   {
@@ -525,12 +537,13 @@ describe("MonitorRecommendationCatalog", () => {
   });
 
   /*
-   * Services are the only resource type whose recommendation set is not a
-   * constant. Everything below is about the seam between "what applies to this
-   * resource" and "what this catalog can ever produce" — the two are the same
-   * question for nine resource types and different for the tenth, and the
-   * failure mode of conflating them is a page that offers JVM heap monitors to
-   * a Go service.
+   * Services were the first resource type whose recommendation set is not a
+   * constant (databases and RUM applications have suites of their own below).
+   * Everything here is about the seam between "what applies to this resource"
+   * and "what this catalog can ever produce" — the same question for every
+   * resource type whose set is a constant, and a different one for these, and
+   * the failure mode of conflating them is a page that offers JVM heap
+   * monitors to a Go service.
    */
   describe("context-aware recommendations", () => {
     const AGNOSTIC_COUNT: number = getServiceAlertTemplates(null).length;
@@ -603,9 +616,16 @@ describe("MonitorRecommendationCatalog", () => {
       for (const resourceType of Object.values(
         MonitorRecommendationResourceType,
       )) {
+        /*
+         * The three resource types whose set is NOT a constant, each with a
+         * suite of its own below: a service by runtime, a database by engine,
+         * and a RUM application by whether it records session replays (its
+         * budget alerts).
+         */
         if (
           resourceType === MonitorRecommendationResourceType.Service ||
-          resourceType === MonitorRecommendationResourceType.DatabaseServer
+          resourceType === MonitorRecommendationResourceType.DatabaseServer ||
+          resourceType === MonitorRecommendationResourceType.RumApplication
         ) {
           continue;
         }
@@ -617,9 +637,19 @@ describe("MonitorRecommendationCatalog", () => {
             },
           );
 
+        /*
+         * Every fact any resource type reads, set to the value that moves its
+         * own list the most, so a constant set that started reading one of
+         * them would change here.
+         */
         const withContext: Array<string> =
           MonitorRecommendationCatalog.getRecommendations(resourceType, {
             serviceLanguage: "java",
+            databaseEngine: "postgresql",
+            databaseEngineMetricsReported: true,
+            sessionReplayEnabled: true,
+            sessionReplayHasRecorded: true,
+            sessionReplayMonthlyBudgetInGB: 10,
           }).map((recommendation: MonitorRecommendation) => {
             return recommendation.recommendationId;
           });
@@ -906,4 +936,238 @@ describe("MonitorRecommendationCatalog", () => {
       expect(new Set(categories).size).toBe(categories.length);
     });
   });
+
+  /*
+   * RUM applications: the third context-dependent resource type. Every
+   * application is offered the same web vital and error recommendations, but
+   * the session replay budget alerts only once the application records
+   * replays (and, for the monthly pair, has a monthly budget) - the sweep
+   * writes nothing for any other application, so each would be a monitor
+   * that can never fire. The page's side-menu badge counts from the same
+   * answer, so a wrong one inflates the badge on every RUM application.
+   */
+  describe("RUM application recommendations", () => {
+    const FULL_REPLAY_CONTEXT: MonitorRecommendationContext = {
+      sessionReplayEnabled: true,
+      sessionReplayHasRecorded: true,
+      sessionReplayMonthlyBudgetInGB: 10,
+    };
+
+    const BUDGET_TEMPLATE_IDS: Array<string> = [
+      "rum-session-replay-daily-budget-nearly-spent",
+      "rum-session-replay-daily-budget-spent",
+      "rum-session-replay-monthly-budget-nearly-spent",
+      "rum-session-replay-monthly-budget-spent",
+    ];
+
+    function rumRecommendationIds(
+      context?: MonitorRecommendationContext | undefined,
+    ): Array<string> {
+      return MonitorRecommendationCatalog.getRecommendations(
+        MonitorRecommendationResourceType.RumApplication,
+        context,
+      ).map((recommendation: MonitorRecommendation) => {
+        return recommendation.recommendationId;
+      });
+    }
+
+    function idsOf(templates: Array<RumAlertTemplate>): Array<string> {
+      return templates.map((template: RumAlertTemplate) => {
+        return buildRecommendationId(
+          MonitorRecommendationResourceType.RumApplication,
+          template.id,
+        );
+      });
+    }
+
+    it("offers the original seven when nothing is known about the application", () => {
+      const contextFree: Array<string> = rumRecommendationIds();
+
+      expect(contextFree).toHaveLength(7);
+      expect(contextFree).toEqual(idsOf(getRumAlertTemplates(undefined)));
+      expect(rumRecommendationIds({})).toEqual(contextFree);
+
+      for (const templateId of BUDGET_TEMPLATE_IDS) {
+        expect(contextFree).not.toContain(
+          buildRecommendationId(
+            MonitorRecommendationResourceType.RumApplication,
+            templateId,
+          ),
+        );
+      }
+    });
+
+    it("offers all eleven, in the module's order, to an application that records and has a budget", () => {
+      const offered: Array<string> = rumRecommendationIds(FULL_REPLAY_CONTEXT);
+
+      expect(offered).toHaveLength(11);
+      expect(offered).toEqual(idsOf(getAllRumAlertTemplates()));
+    });
+
+    /*
+     * The adapter re-assembles the module's context field by field, so a
+     * field it forgot to forward would read as "not known" - withholding the
+     * alerts on every page while every other test stays green. One case per
+     * field: each moves the count, so each must have arrived.
+     */
+    it("forwards every replay fact to the module", () => {
+      expect(
+        rumRecommendationIds({
+          sessionReplayEnabled: true,
+          sessionReplayHasRecorded: true,
+        }),
+      ).toEqual(
+        idsOf(
+          getRumAlertTemplates({
+            sessionReplayEnabled: true,
+            sessionReplayHasRecorded: true,
+          }),
+        ),
+      );
+      expect(
+        rumRecommendationIds({
+          sessionReplayEnabled: true,
+          sessionReplayHasRecorded: true,
+        }),
+      ).toHaveLength(9);
+      expect(
+        rumRecommendationIds({
+          ...FULL_REPLAY_CONTEXT,
+          sessionReplayEnabled: false,
+        }),
+      ).toHaveLength(7);
+      expect(
+        rumRecommendationIds({
+          ...FULL_REPLAY_CONTEXT,
+          sessionReplayHasRecorded: false,
+        }),
+      ).toHaveLength(7);
+      expect(
+        rumRecommendationIds({
+          ...FULL_REPLAY_CONTEXT,
+          sessionReplayMonthlyBudgetInGB: 0,
+        }),
+      ).toHaveLength(9);
+    });
+
+    it("stays exhaustive, and resolves every budget recommendation by id with no context", () => {
+      /*
+       * The path a dismissal takes: the row stores a recommendation id and
+       * nothing about the application, so lookup has to work without one.
+       */
+      const all: Array<MonitorRecommendation> =
+        MonitorRecommendationCatalog.getAllPossibleRecommendations(
+          MonitorRecommendationResourceType.RumApplication,
+        );
+
+      expect(all).toHaveLength(11);
+      expect(all.length).toBe(getAllRumAlertTemplates().length);
+
+      for (const templateId of BUDGET_TEMPLATE_IDS) {
+        const recommendation: MonitorRecommendation | undefined =
+          MonitorRecommendationCatalog.getRecommendationById(
+            buildRecommendationId(
+              MonitorRecommendationResourceType.RumApplication,
+              templateId,
+            ),
+          );
+
+        expect(recommendation).toBeDefined();
+        expect(recommendation?.templateId).toBe(templateId);
+        expect(recommendation?.resourceType).toBe(
+          MonitorRecommendationResourceType.RumApplication,
+        );
+        expect(recommendation?.monitorType).toBe(MonitorType.Metrics);
+        expect(recommendation?.category).toBe("Session Replay");
+      }
+    });
+
+    it("lists Session Replay last, and only once the budget alerts are offered", () => {
+      const contextFreeCategories: Array<string> =
+        MonitorRecommendationCatalog.getCategories(
+          MonitorRecommendationResourceType.RumApplication,
+        );
+      const fullCategories: Array<string> =
+        MonitorRecommendationCatalog.getCategories(
+          MonitorRecommendationResourceType.RumApplication,
+          FULL_REPLAY_CONTEXT,
+        );
+
+      expect(contextFreeCategories).toEqual(["Core Web Vitals", "Errors"]);
+      expect(fullCategories).toEqual([
+        ...contextFreeCategories,
+        "Session Replay",
+      ]);
+      expect(fullCategories[fullCategories.length - 1]).toBe("Session Replay");
+    });
+
+    it("scopes every budget recommendation's step to the application id", () => {
+      const rumApplicationId: string = ObjectID.generate().toString();
+
+      const budgetRecommendations: Array<MonitorRecommendation> =
+        MonitorRecommendationCatalog.getRecommendations(
+          MonitorRecommendationResourceType.RumApplication,
+          FULL_REPLAY_CONTEXT,
+        ).filter((item: MonitorRecommendation) => {
+          return item.category === "Session Replay";
+        });
+
+      // Or the loop below would pass having checked nothing.
+      expect(
+        budgetRecommendations.map((recommendation: MonitorRecommendation) => {
+          return recommendation.templateId;
+        }),
+      ).toEqual(BUDGET_TEMPLATE_IDS);
+
+      for (const recommendation of budgetRecommendations) {
+        const step: MonitorStep = recommendation.getMonitorStep({
+          resourceIdentifier: rumApplicationId,
+          onlineMonitorStatusId: ObjectID.generate(),
+          offlineMonitorStatusId: ObjectID.generate(),
+          defaultIncidentSeverityId: ObjectID.generate(),
+          defaultAlertSeverityId: ObjectID.generate(),
+          monitorName: "Storefront",
+        });
+
+        expect(
+          step.data?.metricMonitor?.telemetryServiceIds?.map((id: ObjectID) => {
+            return id.toString();
+          }),
+        ).toEqual([rumApplicationId]);
+      }
+    });
+
+    it("keeps the three context-dependent resource types independent", () => {
+      // Replay facts change nothing for a service or a database...
+      expect(
+        MonitorRecommendationCatalog.getRecommendations(
+          MonitorRecommendationResourceType.Service,
+          FULL_REPLAY_CONTEXT,
+        ).map((recommendation: MonitorRecommendation) => {
+          return recommendation.recommendationId;
+        }),
+      ).toEqual(
+        MonitorRecommendationCatalog.getRecommendations(
+          MonitorRecommendationResourceType.Service,
+        ).map((recommendation: MonitorRecommendation) => {
+          return recommendation.recommendationId;
+        }),
+      );
+      expect(
+        MonitorRecommendationCatalog.getRecommendations(
+          MonitorRecommendationResourceType.DatabaseServer,
+          FULL_REPLAY_CONTEXT,
+        ),
+      ).toEqual([]);
+
+      // ...and a runtime or an engine changes nothing for a RUM application.
+      expect(
+        rumRecommendationIds({
+          serviceLanguage: "java",
+          databaseEngine: "postgresql",
+          databaseEngineMetricsReported: true,
+        }),
+      ).toEqual(rumRecommendationIds());
+    });
+  });
 });

package/Tests/Types/Monitor/Recommendation/MonitorRecommendationUtil.test.ts

@@ -181,6 +181,33 @@ describe("MonitorRecommendationUtil", () => {
         expect(new Set(names).size).toBe(names.length);
       }
     });
+
+    it("produces distinct names within the set a recording RUM application with a budget is offered", () => {
+      /*
+       * The context-free loop above never sees the session replay budget
+       * alerts - they are only offered to an application that records
+       * replays - so it proves nothing for them. With every replay fact
+       * known, one application is offered all eleven at once, including two
+       * pairs that read the same series at different thresholds.
+       */
+      const names: Array<string> =
+        MonitorRecommendationCatalog.getRecommendations(
+          MonitorRecommendationResourceType.RumApplication,
+          {
+            sessionReplayEnabled: true,
+            sessionReplayHasRecorded: true,
+            sessionReplayMonthlyBudgetInGB: 10,
+          },
+        ).map((recommendation: MonitorRecommendation) => {
+          return MonitorRecommendationUtil.getMonitorName({
+            recommendation: recommendation,
+            resourceDisplayName: "Storefront",
+          });
+        });
+
+      expect(names).toHaveLength(11);
+      expect(new Set(names).size).toBe(names.length);
+    });
   });
 
   describe("getMonitorStep — every recommendation, every resource type", () => {
@@ -991,6 +1018,92 @@ describe("MonitorRecommendationUtil", () => {
     });
   });
 
+  /*
+   * The RUM session replay budget alerts come in two pairs that read ONE
+   * series each, differing only in threshold. The already-created diff must
+   * still tell the two halves of a pair apart - or creating the Warning hides
+   * the Critical card - and must scope each monitor to its application: the
+   * daily value is posted identically under every recording application, so
+   * nothing but the application id distinguishes one application's monitor
+   * from another's.
+   */
+  describe("RUM session replay budget fingerprints", () => {
+    const APPLICATION_A: string = ObjectID.generate().toString();
+    const APPLICATION_B: string = ObjectID.generate().toString();
+
+    const budgetRecommendations: Array<MonitorRecommendation> =
+      MonitorRecommendationCatalog.getRecommendations(
+        MonitorRecommendationResourceType.RumApplication,
+        {
+          sessionReplayEnabled: true,
+          sessionReplayHasRecorded: true,
+          sessionReplayMonthlyBudgetInGB: 10,
+        },
+      ).filter((recommendation: MonitorRecommendation) => {
+        return recommendation.category === "Session Replay";
+      });
+
+    function stepOn(
+      recommendation: MonitorRecommendation,
+      resourceIdentifier: string,
+    ): MonitorStep {
+      return recommendation.getMonitorStep(
+        buildArgs({ resourceIdentifier: resourceIdentifier }),
+      );
+    }
+
+    it("reads the application id off the step as the resource identifier", () => {
+      expect(budgetRecommendations).toHaveLength(4);
+
+      for (const recommendation of budgetRecommendations) {
+        const fingerprint: MonitorRecommendationFingerprint | undefined =
+          MonitorRecommendationUtil.getFingerprintFromMonitorStep(
+            stepOn(recommendation, APPLICATION_A),
+          );
+
+        expect(fingerprint?.configKind).toBe("metricMonitor");
+        expect(fingerprint?.resourceIdentifier).toBe(APPLICATION_A);
+      }
+    });
+
+    it("never lets one threshold of a pair cover the other", () => {
+      for (const created of budgetRecommendations) {
+        const covered: Set<string> =
+          MonitorRecommendationUtil.getCoveredRecommendationIds({
+            recommendations: budgetRecommendations,
+            existingMonitorSteps: [stepOn(created, APPLICATION_A)],
+            args: buildArgs({ resourceIdentifier: APPLICATION_A }),
+          });
+
+        expect([...covered]).toEqual([created.recommendationId]);
+      }
+    });
+
+    it("never lets one application's budget monitor cover another application's", () => {
+      const existing: Array<MonitorStep> = budgetRecommendations.map(
+        (recommendation: MonitorRecommendation) => {
+          return stepOn(recommendation, APPLICATION_A);
+        },
+      );
+
+      expect(
+        MonitorRecommendationUtil.getCoveredRecommendationIds({
+          recommendations: budgetRecommendations,
+          existingMonitorSteps: existing,
+          args: buildArgs({ resourceIdentifier: APPLICATION_B }),
+        }).size,
+      ).toBe(0);
+
+      expect(
+        MonitorRecommendationUtil.getCoveredRecommendationIds({
+          recommendations: budgetRecommendations,
+          existingMonitorSteps: existing,
+          args: buildArgs({ resourceIdentifier: APPLICATION_A }),
+        }).size,
+      ).toBe(budgetRecommendations.length);
+    });
+  });
+
   /*
    * A database's monitors are generic Metrics monitors whose only resource
    * identity is the `oneuptime.database.server.id` filter on every query. The