@oneuptime/common 12.0.13 → 12.0.14

package/Types/Monitor/Recommendation/MonitorRecommendationCatalog.ts

@@ -5,6 +5,7 @@ import RecommendationType from "../../Recommendation/RecommendationType";
 import {
   MonitorRecommendation,
   MonitorRecommendationArgs,
+  MonitorRecommendationContext,
   MonitorRecommendationResourceType,
   MonitorRecommendationSeverity,
   buildRecommendationId,
@@ -46,6 +47,11 @@ import {
   RumAlertTemplate,
   getAllRumAlertTemplates,
 } from "../RumAlertTemplates";
+import {
+  ServiceAlertTemplate,
+  getAllServiceAlertTemplates,
+  getServiceAlertTemplates,
+} from "../ServiceAlertTemplates";
 
 /*
  * A resource type's entry in the registry.
@@ -70,17 +76,49 @@ export interface MonitorRecommendationResourceTypeDefinition {
     | "clusterIdentifier"
     | "hostIdentifier"
     | "fleetIdentifier"
-    | "rumApplicationId";
+    | "rumApplicationId"
+    | "serviceId";
   icon: IconProp;
-  getRecommendations: () => Array<MonitorRecommendation>;
+  /*
+   * What to recommend for ONE resource of this type.
+   *
+   * Nine of the ten resource types ignore the argument entirely — every
+   * Kubernetes cluster is offered the same eighteen recommendations, and a
+   * zero-argument function satisfies this type, so those nine are declared
+   * exactly as they were. Services are the exception: see
+   * `MonitorRecommendationContext`.
+   *
+   * Passing no context means "nothing is known about this resource", and the
+   * only honest answer to that is the context-free subset. It does NOT mean
+   * "give me everything" — that is what `getAllPossibleRecommendations` is
+   * for, and conflating the two is how a UI ends up offering JVM monitors to
+   * a Go service.
+   */
+  getRecommendations: (
+    context?: MonitorRecommendationContext | undefined,
+  ) => Array<MonitorRecommendation>;
+  /*
+   * Every recommendation this resource type can EVER produce, across every
+   * context. Only worth setting on a resource type whose set actually varies;
+   * `getAllRecommendations` falls back to `getRecommendations()` for the rest.
+   *
+   * This is what the registry-wide invariants have to run against — globally
+   * unique recommendation ids, globally distinct coverage fingerprints,
+   * a severity every mapper understands. Running them over the context-free
+   * subset instead would leave every language-specific template unchecked,
+   * which is precisely the set most likely to collide.
+   */
+  getAllPossibleRecommendations?:
+    | (() => Array<MonitorRecommendation>)
+    | undefined;
 }
 
 /*
- * The structural shape every `<X>AlertTemplate` interface shares. The eight
- * modules declare eight separate interfaces that differ only in the literal
+ * The structural shape every `<X>AlertTemplate` interface shares. The ten
+ * modules declare ten separate interfaces that differ only in the literal
  * union used for `category` (and the args type of `getMonitorStep`), so the
  * normalizer below widens `category` to `string` rather than trying to union
- * eight unrelated literal unions.
+ * ten unrelated literal unions.
  */
 interface StructuralAlertTemplate {
   id: string;
@@ -307,6 +345,55 @@ function getRumRecommendations(): Array<MonitorRecommendation> {
   });
 }
 
+/*
+ * The Service adapter, and the only one that is two functions rather than one.
+ *
+ * `getServiceRecommendations` answers "what should THIS service be offered",
+ * which depends on its runtime. `getAllServiceRecommendations` answers "what
+ * can a service ever be offered", which does not. Both go through the same
+ * normalizer so a template cannot be shaped differently depending on which
+ * door it came through.
+ */
+function normalizeServiceTemplate(
+  template: ServiceAlertTemplate,
+): MonitorRecommendation {
+  return normalize({
+    resourceType: MonitorRecommendationResourceType.Service,
+    /*
+     * Read off the template rather than fixed, because the service catalog —
+     * like RUM's — deliberately spans metric, trace and exception monitors.
+     */
+    monitorType: template.monitorType,
+    template: template,
+    getMonitorStep: (args: MonitorRecommendationArgs) => {
+      return template.getMonitorStep({
+        serviceId: args.resourceIdentifier,
+        onlineMonitorStatusId: args.onlineMonitorStatusId,
+        offlineMonitorStatusId: args.offlineMonitorStatusId,
+        defaultIncidentSeverityId: args.defaultIncidentSeverityId,
+        defaultAlertSeverityId: args.defaultAlertSeverityId,
+        monitorName: args.monitorName,
+      });
+    },
+  });
+}
+
+function getServiceRecommendations(
+  context?: MonitorRecommendationContext | undefined,
+): Array<MonitorRecommendation> {
+  return getServiceAlertTemplates(context?.serviceLanguage).map(
+    (template: ServiceAlertTemplate) => {
+      return normalizeServiceTemplate(template);
+    },
+  );
+}
+
+function getAllServiceRecommendations(): Array<MonitorRecommendation> {
+  return getAllServiceAlertTemplates().map((template: ServiceAlertTemplate) => {
+    return normalizeServiceTemplate(template);
+  });
+}
+
 const RESOURCE_TYPE_DEFINITIONS: Array<MonitorRecommendationResourceTypeDefinition> =
   [
     {
@@ -385,6 +472,19 @@ const RESOURCE_TYPE_DEFINITIONS: Array<MonitorRecommendationResourceTypeDefiniti
       icon: IconProp.Globe,
       getRecommendations: getRumRecommendations,
     },
+    {
+      resourceType: MonitorRecommendationResourceType.Service,
+      monitorTypes: [
+        MonitorType.Metrics,
+        MonitorType.Traces,
+        MonitorType.Exceptions,
+      ],
+      resourceLabel: "Service",
+      identifierFieldName: "serviceId",
+      icon: IconProp.Code,
+      getRecommendations: getServiceRecommendations,
+      getAllPossibleRecommendations: getAllServiceRecommendations,
+    },
   ];
 
 export default class MonitorRecommendationCatalog {
@@ -402,8 +502,14 @@ export default class MonitorRecommendationCatalog {
     );
   }
 
+  /*
+   * What to offer ONE resource. `context` is what a caller knows about that
+   * specific resource; omitting it is a valid answer meaning "nothing", and
+   * yields the subset that is true of every resource of this type.
+   */
   public static getRecommendations(
     resourceType: MonitorRecommendationResourceType,
+    context?: MonitorRecommendationContext | undefined,
   ): Array<MonitorRecommendation> {
     const definition: MonitorRecommendationResourceTypeDefinition | undefined =
       this.getResourceTypeDefinition(resourceType);
@@ -412,13 +518,26 @@ export default class MonitorRecommendationCatalog {
       return [];
     }
 
-    return definition.getRecommendations();
+    return definition.getRecommendations(context);
   }
 
+  /*
+   * Every recommendation the catalog can produce, for any resource, in any
+   * context.
+   *
+   * Deliberately takes no context. Its two jobs — resolving a
+   * `recommendationId` back to its recommendation, and giving the
+   * registry-wide invariant tests something exhaustive to run over — are both
+   * jobs where filtering would silently weaken the answer. Resolving an id in
+   * particular has to work from a dismissal row alone, which carries no
+   * language.
+   */
   public static getAllRecommendations(): Array<MonitorRecommendation> {
     return RESOURCE_TYPE_DEFINITIONS.flatMap(
       (definition: MonitorRecommendationResourceTypeDefinition) => {
-        return definition.getRecommendations();
+        return definition.getAllPossibleRecommendations
+          ? definition.getAllPossibleRecommendations()
+          : definition.getRecommendations();
       },
     );
   }
@@ -441,10 +560,14 @@ export default class MonitorRecommendationCatalog {
    */
   public static getCategories(
     resourceType: MonitorRecommendationResourceType,
+    context?: MonitorRecommendationContext | undefined,
   ): Array<string> {
     const categories: Array<string> = [];
 
-    for (const recommendation of this.getRecommendations(resourceType)) {
+    for (const recommendation of this.getRecommendations(
+      resourceType,
+      context,
+    )) {
       if (!categories.includes(recommendation.category)) {
         categories.push(recommendation.category);
       }

package/Types/Monitor/Recommendation/MonitorRecommendationTypes.ts

@@ -1,5 +1,6 @@
 import ObjectID from "../../ObjectID";
 import RecommendationType from "../../Recommendation/RecommendationType";
+import { ServiceLanguage } from "../../Service/ServiceLanguage";
 import MonitorStep from "../MonitorStep";
 import MonitorType from "../MonitorType";
 
@@ -10,9 +11,14 @@ import MonitorType from "../MonitorType";
  * member here and an adapter in `MonitorRecommendationCatalog.ts`, and the
  * catalog's own tests fail until both exist.
  *
- * These values are persisted nowhere. They are a UI/registry key only, so
- * they are free to differ from `MonitorType` (which they do: `DockerSwarm`
- * here vs `"Docker Swarm"` there).
+ * These values are NOT persisted directly, but they ARE written into
+ * `RecommendationDismissal.resourceType` (a free-text column) and into every
+ * `recommendationId` via `buildRecommendationId`. Renaming a member orphans
+ * the dismissals recorded under the old value, exactly as renaming a
+ * `RecommendationType` member does.
+ *
+ * They are free to differ from `MonitorType`, and they do: `DockerSwarm` here
+ * vs `"Docker Swarm"` there.
  */
 export enum MonitorRecommendationResourceType {
   Kubernetes = "Kubernetes",
@@ -24,13 +30,46 @@ export enum MonitorRecommendationResourceType {
   Ceph = "Ceph",
   IoTDevice = "IoTDevice",
   RumApplication = "RumApplication",
+  /*
+   * An APM telemetry service — a backend process reporting OTel traces,
+   * metrics and exceptions under a `service.name`. The only resource type
+   * whose recommendation set is not a constant: see
+   * `MonitorRecommendationContext`.
+   */
+  Service = "Service",
+}
+
+/*
+ * What is known about ONE resource, for resource types whose recommendation
+ * set depends on it.
+ *
+ * Every other resource type answers "what should I monitor here?" from the
+ * resource type alone — every Kubernetes cluster gets the same eighteen
+ * recommendations. Services do not: the runtime signals worth alerting on for
+ * a Java service (heap pressure, GC pause time, thread exhaustion) do not
+ * exist on a Go service, and recommending them there produces monitors that
+ * silently never fire, which is worse than recommending nothing.
+ *
+ * Optional everywhere, and every field inside it is optional too, so a caller
+ * that knows nothing still gets the language-agnostic recommendations rather
+ * than an empty list or a guess.
+ */
+export interface MonitorRecommendationContext {
+  /*
+   * The service's detected runtime. `null` and `undefined` mean the same
+   * thing here — nothing identified the runtime — and both are accepted
+   * because `detectServiceLanguage` returns `null` while an absent field is
+   * `undefined`, and forcing every call site to normalize one into the other
+   * is how a `null` ends up narrowing to some default language by accident.
+   */
+  serviceLanguage?: ServiceLanguage | null | undefined;
 }
 
 /*
  * Every template module declares its own
  * `<X>AlertTemplateSeverity = "Critical" | "Warning"` union. They are
  * identical, so the registry uses one shared type rather than a union of
- * eight structurally-equal unions.
+ * ten structurally-equal unions.
  */
 export type MonitorRecommendationSeverity = "Critical" | "Warning";
 
@@ -42,11 +81,12 @@ export type MonitorRecommendationSeverity = "Critical" | "Warning";
  *   hostIdentifier    -> Host, Docker, Podman
  *   fleetIdentifier   -> IoTDevice
  *   rumApplicationId  -> RUM application
+ *   serviceId         -> APM service
  *
  * The registry normalizes that single difference into `resourceIdentifier`
  * and each catalog adapter renames it back on the way into the module's own
  * `getMonitorStep`. Nothing else about the args differs, which is why this
- * one interface can drive all eight.
+ * one interface can drive all ten.
  */
 export interface MonitorRecommendationArgs {
   resourceIdentifier: string;
@@ -89,9 +129,9 @@ export interface MonitorRecommendation {
  * Registry-wide unique id for a recommendation.
  *
  * Every template module happens to self-prefix its ids today (`host-high-cpu`,
- * `docker-high-cpu`, `podman-high-cpu`), so the 76 template ids are in fact
- * globally unique right now. That is a convention across eight independently
- * maintained files, not a contract — each module only guarantees uniqueness
+ * `docker-high-cpu`, `podman-high-cpu`), so every shipped template id is in
+ * fact globally unique right now. That is a convention across ten
+ * independently maintained files, not a contract — each module only guarantees uniqueness
  * WITHIN itself. Prefixing here makes the registry correct regardless: without
  * it, the day two modules pick the same id, selecting one card in the UI would
  * silently also select the other. `MonitorRecommendationCatalog.test.ts` keeps