@oneuptime/common 14.0.2 → 14.0.5

package/Types/Monitor/Recommendation/MonitorRecommendationCatalog.ts

@@ -15,6 +15,11 @@ import {
   CephAlertTemplate,
   getAllCephAlertTemplates,
 } from "../CephAlertTemplates";
+import {
+  DatabaseAlertTemplate,
+  getAllDatabaseAlertTemplates,
+  getDatabaseAlertTemplates,
+} from "../DatabaseAlertTemplates";
 import {
   DockerAlertTemplate,
   getAllDockerAlertTemplates,
@@ -82,15 +87,16 @@ export interface MonitorRecommendationResourceTypeDefinition {
     | "hostIdentifier"
     | "fleetIdentifier"
     | "rumApplicationId"
-    | "serviceId";
+    | "serviceId"
+    | "databaseServerId";
   icon: IconProp;
   /*
    * 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
+   * Most 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 are declared
+   * exactly as they were. Services and databases are the exceptions: see
    * `MonitorRecommendationContext`.
    *
    * Passing no context means "nothing is known about this resource", and the
@@ -419,6 +425,69 @@ function getAllServiceRecommendations(): Array<MonitorRecommendation> {
   });
 }
 
+/*
+ * The database adapter — two functions for the same reason as Service's.
+ *
+ * `getDatabaseRecommendations` answers "what should THIS database be
+ * offered", which depends on its engine and on whether its engine metrics
+ * have ever arrived; `getAllDatabaseRecommendations` answers "what can a
+ * database ever be offered".
+ */
+function normalizeDatabaseTemplate(
+  template: DatabaseAlertTemplate,
+): MonitorRecommendation {
+  return normalize({
+    resourceType: MonitorRecommendationResourceType.DatabaseServer,
+    monitorType: template.monitorType,
+    template: template,
+    getMonitorStep: (args: MonitorRecommendationArgs) => {
+      return template.getMonitorStep({
+        databaseServerId: args.resourceIdentifier,
+        onlineMonitorStatusId: args.onlineMonitorStatusId,
+        offlineMonitorStatusId: args.offlineMonitorStatusId,
+        defaultIncidentSeverityId: args.defaultIncidentSeverityId,
+        defaultAlertSeverityId: args.defaultAlertSeverityId,
+        monitorName: args.monitorName,
+      });
+    },
+  });
+}
+
+/*
+ * No engine -> nothing, and engine metrics known NOT to have arrived ->
+ * nothing. Both are the honest answer rather than a gap: every database
+ * template reads one engine receiver's metrics, so without the engine there
+ * is no template that applies, and without the metrics every template would
+ * be a monitor over data nobody sends (and "Engine Metrics Stopped" would
+ * fire the moment it was created). The page explains both states — see
+ * RecommendationResourceRegistry's `describeContext` for databases.
+ */
+function getDatabaseRecommendations(
+  context?: MonitorRecommendationContext | undefined,
+): Array<MonitorRecommendation> {
+  if (!context?.databaseEngine) {
+    return [];
+  }
+
+  if (context.databaseEngineMetricsReported === false) {
+    return [];
+  }
+
+  return getDatabaseAlertTemplates(context.databaseEngine).map(
+    (template: DatabaseAlertTemplate) => {
+      return normalizeDatabaseTemplate(template);
+    },
+  );
+}
+
+function getAllDatabaseRecommendations(): Array<MonitorRecommendation> {
+  return getAllDatabaseAlertTemplates().map(
+    (template: DatabaseAlertTemplate) => {
+      return normalizeDatabaseTemplate(template);
+    },
+  );
+}
+
 const RESOURCE_TYPE_DEFINITIONS: Array<MonitorRecommendationResourceTypeDefinition> =
   [
     {
@@ -518,6 +587,15 @@ const RESOURCE_TYPE_DEFINITIONS: Array<MonitorRecommendationResourceTypeDefiniti
       getRecommendations: getServiceRecommendations,
       getAllPossibleRecommendations: getAllServiceRecommendations,
     },
+    {
+      resourceType: MonitorRecommendationResourceType.DatabaseServer,
+      monitorTypes: [MonitorType.Metrics],
+      resourceLabel: "Database",
+      identifierFieldName: "databaseServerId",
+      icon: IconProp.Database,
+      getRecommendations: getDatabaseRecommendations,
+      getAllPossibleRecommendations: getAllDatabaseRecommendations,
+    },
   ];
 
 export default class MonitorRecommendationCatalog {
@@ -568,13 +646,36 @@ export default class MonitorRecommendationCatalog {
   public static getAllRecommendations(): Array<MonitorRecommendation> {
     return RESOURCE_TYPE_DEFINITIONS.flatMap(
       (definition: MonitorRecommendationResourceTypeDefinition) => {
-        return definition.getAllPossibleRecommendations
-          ? definition.getAllPossibleRecommendations()
-          : definition.getRecommendations();
+        return this.getAllPossibleRecommendations(definition.resourceType);
       },
     );
   }
 
+  /*
+   * Every recommendation ONE resource type can ever produce, across every
+   * context — `getAllRecommendations` narrowed to a single type.
+   *
+   * This, not `getRecommendations(resourceType)`, is what a per-type
+   * invariant has to run over: with no context a database is offered nothing
+   * at all (there is no engine-agnostic database template) and a service only
+   * its language-agnostic subset, so a check written against the context-free
+   * set would silently skip every engine- and runtime-specific template.
+   */
+  public static getAllPossibleRecommendations(
+    resourceType: MonitorRecommendationResourceType,
+  ): Array<MonitorRecommendation> {
+    const definition: MonitorRecommendationResourceTypeDefinition | undefined =
+      this.getResourceTypeDefinition(resourceType);
+
+    if (!definition) {
+      return [];
+    }
+
+    return definition.getAllPossibleRecommendations
+      ? definition.getAllPossibleRecommendations()
+      : definition.getRecommendations();
+  }
+
   public static getRecommendationById(
     recommendationId: string,
   ): MonitorRecommendation | undefined {

package/Types/Monitor/Recommendation/MonitorRecommendationTypes.ts

@@ -33,27 +33,37 @@ export enum MonitorRecommendationResourceType {
   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`.
+   * metrics and exceptions under a `service.name`. Its recommendation set is
+   * not a constant: see `MonitorRecommendationContext`.
    */
   Service = "Service",
+  /*
+   * A database server (the DatabaseServer model). Its recommendation set
+   * depends on its engine and on whether engine metrics have ever arrived —
+   * see `MonitorRecommendationContext`. Distinct from `MonitorType.Database`,
+   * the probe-based Database Health monitor: these recommendations create
+   * ordinary Metrics monitors over the engine's collector-receiver metrics.
+   */
+  DatabaseServer = "DatabaseServer",
 }
 
 /*
  * 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
+ * Most resource types answer "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.
+ * silently never fire, which is worse than recommending nothing. Databases
+ * are the same by engine: PostgreSQL's receiver and Redis's share no metric
+ * name.
  *
  * 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.
+ * that knows nothing still gets the subset that is true of every resource of
+ * the type — the language-agnostic recommendations for a service, and none
+ * for a database — rather than a guess.
  */
 export interface MonitorRecommendationContext {
   /*
@@ -64,6 +74,24 @@ export interface MonitorRecommendationContext {
    * is how a `null` ends up narrowing to some default language by accident.
    */
   serviceLanguage?: ServiceLanguage | null | undefined;
+  /*
+   * A database's engine — its `dbSystem`, a semconv `db.system.name` value
+   * such as "postgresql" or "redis". It selects the templates of the
+   * collector receivers that monitor that engine (so MariaDB gets MySQL's,
+   * see `getDatabaseAlertTemplates`). Every database template reads one
+   * receiver's metric names, so without an engine nothing applies — unlike a
+   * service, a database has no engine-agnostic subset.
+   */
+  databaseEngine?: string | null | undefined;
+  /*
+   * Whether the database's engine metrics (a collector database receiver or
+   * the Database Agent) have ever arrived. `false` withholds every database
+   * recommendation: on a database seen only through its clients' spans or
+   * as a container, each would be a monitor over metrics nobody sends — and
+   * the "engine metrics stopped" one would fire the moment it was created.
+   * `null` / `undefined` mean "not known" and withhold nothing.
+   */
+  databaseEngineMetricsReported?: boolean | null | undefined;
 }
 
 /*
@@ -84,6 +112,7 @@ export type MonitorRecommendationSeverity = "Critical" | "Warning";
  *   fleetIdentifier   -> IoTDevice
  *   rumApplicationId  -> RUM application
  *   serviceId         -> APM service
+ *   databaseServerId  -> Database server
  *
  * The registry normalizes that single difference into `resourceIdentifier`
  * and each catalog adapter renames it back on the way into the module's own

package/Types/Monitor/Recommendation/MonitorRecommendationUtil.ts

@@ -8,6 +8,7 @@ import MonitorSteps from "../MonitorSteps";
 import MonitorCriteriaInstance from "../MonitorCriteriaInstance";
 import { CriteriaIncident } from "../CriteriaIncident";
 import { CriteriaAlert } from "../CriteriaAlert";
+import { DATABASE_SERVER_ID_SCOPE_ATTRIBUTE } from "../DatabaseAlertTemplates";
 import MonitorRecommendationSeverityMapper from "./MonitorRecommendationSeverityMapper";
 import {
   MonitorRecommendation,
@@ -23,8 +24,10 @@ import {
  *
  * Infrastructure configs carry a metric view plus a named resource
  * identifier. RUM uses generic metric, trace and exception configs, where the
- * application id lives in `telemetryServiceIds`. The optional fields below are
- * the stable query inputs that distinguish those shapes.
+ * application id lives in `telemetryServiceIds`. Databases use generic metric
+ * configs scoped by an `oneuptime.database.server.id` query filter. The
+ * optional fields below are the stable query inputs that distinguish those
+ * shapes.
  */
 interface RecommendationMonitorStepConfig {
   clusterIdentifier?: string | undefined;
@@ -389,6 +392,7 @@ export default class MonitorRecommendationUtil {
       config.hostIdentifier ||
       config.fleetIdentifier ||
       this.getTelemetryResourceIdentifier(config) ||
+      this.getAttributeScopedResourceIdentifier(config) ||
       "";
 
     const metricNames: Array<string> = [];
@@ -492,6 +496,43 @@ export default class MonitorRecommendationUtil {
       .join(",");
   }
 
+  /*
+   * The resource a metric step is scoped to by an attribute FILTER rather than
+   * by an identifier field or `telemetryServiceIds` — a database's metric
+   * monitors, which filter every query on `oneuptime.database.server.id`.
+   *
+   * The filter is already part of the fingerprint through `queryAttributes`,
+   * so two databases' monitors never collide; this only makes the step's
+   * resource identity explicit, so "which resource does this monitor watch"
+   * has the same answer for a database as for every other resource type.
+   * Values are deduped and sorted so a multi-query template scoped the same
+   * way on every query reads as one resource.
+   */
+  private static getAttributeScopedResourceIdentifier(
+    config: RecommendationMonitorStepConfig,
+  ): string {
+    const values: Set<string> = new Set<string>();
+
+    for (const queryConfig of config.metricViewConfig?.queryConfigs || []) {
+      const attributes: unknown =
+        queryConfig?.metricQueryData?.filterData?.["attributes"];
+
+      if (!attributes || typeof attributes !== "object") {
+        continue;
+      }
+
+      const value: unknown = (attributes as Record<string, unknown>)[
+        DATABASE_SERVER_ID_SCOPE_ATTRIBUTE
+      ];
+
+      if (typeof value === "string" && value.trim()) {
+        values.add(value.trim());
+      }
+    }
+
+    return Array.from(values).sort().join(",");
+  }
+
   /*
    * Query inputs that do not live in a metric view. They must participate in
    * coverage identity: an all-span trace monitor does not cover an error-span

package/Types/Monitor/Recommendation/RecommendationCriteriaBuilder.ts

@@ -228,6 +228,40 @@ export interface UnhealthyCriteriaArgs {
   additionalFilters?: Array<AdditionalCriteriaFilterSpec> | undefined;
   filterCondition?: FilterCondition | undefined;
   treatNoDataAsZero?: boolean | undefined;
+  /*
+   * Fire when the window holds NO samples at all, whatever the threshold.
+   * For heartbeat-style criteria, where the metric going silent is itself
+   * the outage — a database receiver that cannot connect emits nothing, so
+   * "the engine's own metrics stopped" is the only telemetry-side signal of
+   * a database that is down. Takes precedence over `treatNoDataAsZero`:
+   * the two are different answers to the same question and a criteria can
+   * only give one.
+   *
+   * Only ever set on the UNHEALTHY side. The recovery criteria keeps the
+   * default Ignore, so a silent window matches neither criteria and the
+   * monitor holds its offline status until data comes back.
+   */
+  triggerOnNoData?: boolean | undefined;
+}
+
+/*
+ * The no-data policy a criteria's filters carry. Undefined — the field left
+ * off entirely — rather than an explicit Ignore, so every criteria that never
+ * asked for one serializes exactly as it did before either option existed.
+ */
+function getNoDataPolicy(data: {
+  treatNoDataAsZero?: boolean | undefined;
+  triggerOnNoData?: boolean | undefined;
+}): NoDataPolicy | undefined {
+  if (data.triggerOnNoData) {
+    return NoDataPolicy.Trigger;
+  }
+
+  if (data.treatNoDataAsZero) {
+    return NoDataPolicy.TreatAsZero;
+  }
+
+  return undefined;
 }
 
 export function buildUnhealthyCriteriaInstance(
@@ -253,9 +287,10 @@ export function buildUnhealthyCriteriaInstance(
       value: args.value,
       metricAggregationType: args.metricAggregationType ?? SustainedEvaluation,
       additionalFilters: args.additionalFilters,
-      onNoDataPolicy: args.treatNoDataAsZero
-        ? NoDataPolicy.TreatAsZero
-        : undefined,
+      onNoDataPolicy: getNoDataPolicy({
+        treatNoDataAsZero: args.treatNoDataAsZero,
+        triggerOnNoData: args.triggerOnNoData,
+      }),
     }),
     incidents: [
       {
@@ -348,9 +383,9 @@ export function buildHealthyCriteriaInstance(
       value: value,
       metricAggregationType: args.metricAggregationType ?? SustainedEvaluation,
       additionalFilters: args.additionalFilters,
-      onNoDataPolicy: args.treatNoDataAsZero
-        ? NoDataPolicy.TreatAsZero
-        : undefined,
+      onNoDataPolicy: getNoDataPolicy({
+        treatNoDataAsZero: args.treatNoDataAsZero,
+      }),
       /*
        * Give every additional recovery comparison its own dead band too,
        * derived the same way as the primary one.

package/Types/Monitor/SeriesContext/SeriesLabelDisplay.ts

@@ -150,6 +150,21 @@ const FriendlyLabelNames: Record<string, string> = {
   "device.id": "Device",
   "device.name": "Device",
 
+  /*
+   * --- Databases ---
+   *
+   * Ingest stamps every row of a database's own telemetry with the
+   * DatabaseServer it resolved to, so a monitor that groups by
+   * `oneuptime.database.server.id` alerts once per database. The rest are
+   * the collector receivers' own identities of one part of a database, for
+   * node-, tablespace- and replica-level monitors.
+   */
+  "oneuptime.database.server.name": "Database",
+  "oneuptime.database.server.id": "Database ID",
+  "elasticsearch.node.name": "Elasticsearch Node",
+  tablespace_name: "Tablespace",
+  replication_client: "Replica",
+
   // --- Services / RUM / telemetry ---
   "service.name": "Service",
   "oneuptime.service.name": "Service",
@@ -251,6 +266,17 @@ const LabelPriority: Record<string, number> = {
   "service.instance.id": 22,
   "service.name": 40,
   "oneuptime.service.name": 40,
+  /*
+   * Databases: the part that breached (a node, a tablespace, a replica)
+   * first, then the database it belongs to. The database's id is a UUID,
+   * pushed to the end with the other ids — correct, but not what a human
+   * scans for.
+   */
+  "elasticsearch.node.name": 25,
+  tablespace_name: 30,
+  replication_client: 30,
+  "oneuptime.database.server.name": 40,
+  "oneuptime.database.server.id": 95,
   "k8s.namespace.name": 50,
   "service.namespace": 50,
   "k8s.node.name": 60,

package/Types/NetworkDevice/DiscoveredHostNamingStatus.ts

@@ -0,0 +1,147 @@
+/*
+ * Why a discovered host was left without a name, as the probe saw it
+ * (OneUptime issue #3916).
+ *
+ * The report behind this: an ICMP-only scan of twelve kitchen displays named
+ * four of them by reverse DNS and listed the other eight by address, and
+ * nothing anywhere said why. The status message was silent, the probe logged
+ * at debug level, and the Review dialog showed a bare IP. "The device has no
+ * PTR record", "the probe's DNS server timed out", "the server answered
+ * SERVFAIL" and "NetBIOS was never asked" all looked exactly the same — so an
+ * operator who KNEW the devices had names could only conclude the product was
+ * broken, and nobody could tell them which of those it was.
+ *
+ * These codes are that missing sentence, one per naming source. The probe
+ * stamps them on a host only when the source in question left that host
+ * unnamed, the server stores them verbatim in the `discoveredDevices` jsonb,
+ * and the Review dialog turns them into a tooltip beside the address
+ * (DiscoveredHostNamingDiagnosis.ts).
+ *
+ * Short kebab-case strings rather than sentences or raw error text: a scan
+ * can hold tens of thousands of hosts, and the copy belongs to the dashboard,
+ * where it can change without a probe release.
+ *
+ * UNTRUSTED ON THE WAY OUT. Like every other field in that column the value
+ * is whatever the probe's payload said, so every reader goes through the
+ * read* functions below, which answer undefined for anything that is not one
+ * of these exact strings. A value the dashboard does not recognise — a newer
+ * probe's code, or junk — then reads as "no code", which every reader already
+ * handles, rather than as a code it would have to guess the meaning of.
+ */
+
+/*
+ * What the reverse-DNS (PTR) lookup for an address came back with, when it
+ * did not come back with a usable name.
+ */
+export enum DiscoveredHostReverseDnsStatus {
+  /*
+   * The DNS server ANSWERED, and the answer was that this address has no PTR
+   * record — NXDOMAIN, or the reverse name exists with no PTR data. The one
+   * code here that is a fact about the address rather than about the lookup,
+   * and the only one a retry cannot change.
+   */
+  NoRecord = "no-record",
+  /*
+   * A PTR record came back, but no answer in it was usable as a hostname
+   * (ReverseDnsNameUtil refused every one — an in-addr.arpa echo, a name
+   * with a space in it, a name that merely restates the address).
+   */
+  UnusableName = "unusable-name",
+  /*
+   * No answer in time. The probe retries a lookup that fails this way, but
+   * only while the pass's time budget lasts, so a host can carry this code
+   * after one try. The copy that explains it must not claim a retry.
+   */
+  Timeout = "timeout",
+  // The DNS server answered SERVFAIL. Retried like Timeout, on the same terms.
+  ServerFailure = "server-failure",
+  // The DNS server answered REFUSED.
+  Refused = "refused",
+  // Nothing was listening where the probe's DNS server should be.
+  Unreachable = "unreachable",
+  // Any other failure of the lookup itself.
+  Failed = "failed",
+  /*
+   * Never looked up: the naming pass ran out of its wall-clock budget
+   * before reaching this address. The scan's status message says so too.
+   */
+  SkippedTimeBudget = "skipped-time-budget",
+  /*
+   * Never looked up: every lookup the probe had made so far failed without
+   * a single answer, so it judged DNS unusable from where it sits and
+   * stopped asking. The scan's status message says so too.
+   */
+  SkippedNoResolver = "skipped-no-resolver",
+}
+
+/*
+ * What the NetBIOS node status (NBSTAT) lookup for an address came to, when
+ * it did not produce a usable name. Only ever stamped on a scan that asked for
+ * NetBIOS names: a scan that did not is described by its own
+ * `isNetbiosLookupEnabled` column, and repeating that on every host would be
+ * thousands of copies of one scan-wide fact.
+ */
+export enum DiscoveredHostNetbiosStatus {
+  /*
+   * Queried on UDP 137 (and retried, unless the lookup was cut short first),
+   * and never answered.
+   */
+  NoReply = "no-reply",
+  // Answered, but reported no name the naming rules accept.
+  NoUsableName = "no-usable-name",
+  // The query could not be sent from the probe.
+  SendFailed = "send-failed",
+  /*
+   * Never queried: the lookup stopped first — its time budget ran out or its
+   * socket failed. The scan's status message says which.
+   */
+  Skipped = "skipped",
+  // Never queried: the lookup reached the probe's NetBIOS host limit first.
+  SkippedHostCap = "skipped-host-cap",
+  /*
+   * Never queried: NetBIOS is only ever sent to private and CGNAT IPv4
+   * addresses, whoever asks. The dashboard's copy of that rule,
+   * isNetbiosQueryableIPv4Address (NetbiosNameUtil.ts), keeps the Review
+   * dialog from suggesting NetBIOS for such an address, and gives an older
+   * probe's row this code's sentence (#3916).
+   */
+  SkippedIneligibleAddress = "skipped-ineligible-address",
+  /*
+   * Never queried: the scan ran on a global probe, which never sends NetBIOS
+   * queries whatever the scan asks for.
+   */
+  SkippedGlobalProbe = "skipped-global-probe",
+}
+
+const REVERSE_DNS_STATUSES: ReadonlySet<string> = new Set<string>(
+  Object.values(DiscoveredHostReverseDnsStatus),
+);
+
+const NETBIOS_STATUSES: ReadonlySet<string> = new Set<string>(
+  Object.values(DiscoveredHostNetbiosStatus),
+);
+
+/**
+ * The reverse-DNS status a stored value stands for, or undefined when it is
+ * not exactly one of the codes above. Accepts `unknown` because its input is
+ * read out of jsonb, where the declared type is a hope rather than a fact.
+ */
+export function readDiscoveredHostReverseDnsStatus(
+  value: unknown,
+): DiscoveredHostReverseDnsStatus | undefined {
+  return typeof value === "string" && REVERSE_DNS_STATUSES.has(value)
+    ? (value as DiscoveredHostReverseDnsStatus)
+    : undefined;
+}
+
+/**
+ * The NetBIOS status a stored value stands for, or undefined when it is not
+ * exactly one of the codes above. Same contract as the reverse-DNS reader.
+ */
+export function readDiscoveredHostNetbiosStatus(
+  value: unknown,
+): DiscoveredHostNetbiosStatus | undefined {
+  return typeof value === "string" && NETBIOS_STATUSES.has(value)
+    ? (value as DiscoveredHostNetbiosStatus)
+    : undefined;
+}