@oneuptime/common 14.0.2 → 14.0.5

package/Server/Utils/Monitor/MonitorStepResourceIdentity.ts

@@ -4,6 +4,8 @@ import MetricQueryConfigData from "../../../Types/Metrics/MetricQueryConfigData"
 import MetricsViewConfig from "../../../Types/Metrics/MetricsViewConfig";
 import MonitorStep from "../../../Types/Monitor/MonitorStep";
 import MonitorType from "../../../Types/Monitor/MonitorType";
+import SqlConnectionConfig from "../../../Types/Monitor/SqlConnectionConfig";
+import SqlDatabaseType from "../../../Types/Monitor/SqlDatabaseType";
 import ObjectID from "../../../Types/ObjectID";
 import SeriesResourceLabels, {
   SeriesResourceRefs,
@@ -23,10 +25,12 @@ import SeriesResourceLabels, {
  * This module answers the same question from the other, always-present
  * side: "which resources does this MONITOR'S OWN CONFIGURATION point
  * at". A host monitor names its host, a Kubernetes monitor names its
- * cluster, a log monitor names its telemetry services, and any monitor
- * with a metric query can carry resource identity in its attribute
- * filters (e.g. `oneuptime.service.name = checkout-api`). None of that
- * depends on the criteria being grouped.
+ * cluster, a log monitor names its telemetry services, a Database Health
+ * or SQL Query monitor names the host:port of the database it connects
+ * to, and any monitor with a metric query can carry resource identity in
+ * its attribute filters (e.g. `oneuptime.service.name = checkout-api`,
+ * `oneuptime.database.server.id = <id>`, `server.address = db.prod`).
+ * None of that depends on the criteria being grouped.
  *
  * Both modules emit the SAME `SeriesResourceRefs` shape, so the single
  * nine-way resolver in SeriesResourceLinker serves both, and the two can
@@ -150,6 +154,210 @@ export default class MonitorStepResourceIdentity {
       monitorType: input.monitorType,
       refs: input.refs,
     });
+
+    /*
+     * 4. Databases. The two probe monitors that connect to a database — the
+     *    Database Health monitor and the SQL Query monitor — name its
+     *    host:port; metric and trace queries over database telemetry name it
+     *    by `server.address` filter; a log query names it by the
+     *    `oneuptime.database.server.id` stamp its lines carry. All resolve
+     *    to the DatabaseServer that owns the endpoint (or has the id), so
+     *    their alerts and incidents land on that database.
+     */
+    this.collectDatabaseRefs({
+      stepData: stepData,
+      monitorType: input.monitorType,
+      refs: input.refs,
+    });
+  }
+
+  private static collectDatabaseRefs(input: {
+    stepData: NonNullable<MonitorStep["data"]>;
+    monitorType: MonitorType;
+    refs: SeriesResourceRefs;
+  }): void {
+    const stepData: NonNullable<MonitorStep["data"]> = input.stepData;
+
+    const probeEndpoint: string | null = this.getProbeDatabaseEndpoint({
+      stepData: stepData,
+      monitorType: input.monitorType,
+    });
+
+    if (probeEndpoint) {
+      input.refs.databaseServerEndpoints.push(probeEndpoint);
+    }
+
+    /*
+     * Per QUERY, not over the merged filter map the other resource types
+     * use: a port and an engine only mean something next to the address
+     * they were written with, and one step can hold queries on two servers.
+     */
+    for (const viewConfig of this.getMetricViewConfigs(stepData)) {
+      const queryConfigs: Array<MetricQueryConfigData> = Array.isArray(
+        viewConfig?.queryConfigs,
+      )
+        ? viewConfig.queryConfigs
+        : [];
+
+      for (const queryConfig of queryConfigs) {
+        const filterData: unknown = queryConfig?.metricQueryData?.filterData;
+
+        if (!filterData || typeof filterData !== "object") {
+          continue;
+        }
+
+        const metricName: unknown = (filterData as Record<string, unknown>)[
+          "metricName"
+        ];
+
+        input.refs.databaseServerEndpoints.push(
+          ...SeriesResourceLabels.extractDatabaseEndpoints({
+            attributes: this.asAttributeRecord(
+              (filterData as Record<string, unknown>)["attributes"],
+            ),
+            metricName: typeof metricName === "string" ? metricName : null,
+          }),
+        );
+      }
+    }
+
+    /*
+     * Trace monitors filter span attributes. A DB client span names its
+     * server by `server.address` / `server.port` / `db.system.name`, so a
+     * Traces monitor on "error spans calling orders-db" names that database.
+     */
+    const traceAttributes: Record<string, unknown> = this.asAttributeRecord(
+      stepData.traceMonitor?.attributes,
+    );
+
+    input.refs.databaseServerEndpoints.push(
+      ...SeriesResourceLabels.extractDatabaseEndpoints({
+        attributes: traceAttributes,
+      }),
+    );
+
+    /*
+     * Log monitors filter log attributes, and a database's own log lines
+     * (the receiver's query events, or the engine log file the Database
+     * Agent ships) carry the `oneuptime.database.server.id` stamp. Id keys
+     * only — the log query's other attribute filters are left to the
+     * resource types that already read them.
+     */
+    input.refs.databaseServerIds.push(
+      ...SeriesResourceLabels.extractDatabaseServerIds(
+        this.asAttributeRecord(stepData.logMonitor?.attributes) as JSONObject,
+      ),
+    );
+  }
+
+  /*
+   * The canonical endpoint a Database Health or SQL Query monitor connects
+   * to, or null.
+   *
+   * A host holding a `{{monitorSecrets.x}}` reference is skipped: the secret
+   * is only resolved when the step is handed to a probe, and the reference
+   * text is not an address. The probe's port is explicit in the form, and
+   * the engine supplies the default when it is missing.
+   */
+  private static getProbeDatabaseEndpoint(input: {
+    stepData: NonNullable<MonitorStep["data"]>;
+    monitorType: MonitorType;
+  }): string | null {
+    let connection: SqlConnectionConfig | undefined;
+
+    if (input.monitorType === MonitorType.Database) {
+      connection = input.stepData.databaseMonitor;
+    } else if (input.monitorType === MonitorType.SQLQuery) {
+      connection = input.stepData.sqlMonitor;
+    }
+
+    if (!connection || typeof connection !== "object") {
+      return null;
+    }
+
+    const host: unknown = connection.host;
+
+    if (typeof host !== "string" || !host.trim() || host.includes("{{")) {
+      return null;
+    }
+
+    const system: string | null = this.getSqlDatabaseSystem(
+      connection.databaseType,
+    );
+
+    const port: unknown = this.isSqlServerNamedInstance({
+      host: host,
+      system: system,
+    })
+      ? null
+      : connection.port;
+
+    return SeriesResourceLabels.buildDatabaseEndpointRef({
+      address: host,
+      port:
+        typeof port === "number" ||
+        (typeof port === "string" && !port.includes("{{"))
+          ? port
+          : null,
+      system: system,
+    });
+  }
+
+  /*
+   * True when a SQL Server probe connects to a NAMED instance
+   * (`host\instance`). The probe's driver (mssql) splits the host at its
+   * last backslash into an instance name and, when that name is non-empty,
+   * drops the port: it asks SQL Browser for the instance's own port. So the
+   * form's port — pre-filled with 1433 — names nothing, and passing it on
+   * would canonicalize the endpoint to `host:1433`, the DEFAULT instance, and
+   * land a named instance's outage on another server. Without it the
+   * endpoint stays `host\instance` (MSSQLSERVER, the default instance, still
+   * becomes `host:1433`).
+   */
+  private static isSqlServerNamedInstance(input: {
+    host: string;
+    system: string | null;
+  }): boolean {
+    if (input.system !== "microsoft.sql_server") {
+      return false;
+    }
+
+    const backslashIndex: number = input.host.lastIndexOf("\\");
+
+    return (
+      backslashIndex >= 0 &&
+      input.host.substring(backslashIndex + 1).trim().length > 0
+    );
+  }
+
+  /*
+   * The semconv `db.system.name` of a probe engine, for the default port.
+   * SqlDatabaseType's values are display names ("Microsoft SQL Server") that
+   * normalizeDatabaseSystem does not know, so they are mapped here.
+   */
+  private static getSqlDatabaseSystem(databaseType: unknown): string | null {
+    switch (databaseType) {
+      case SqlDatabaseType.PostgreSQL:
+        return "postgresql";
+      case SqlDatabaseType.MySQL:
+        return "mysql";
+      case SqlDatabaseType.MicrosoftSqlServer:
+        return "microsoft.sql_server";
+      default:
+        return null;
+    }
+  }
+
+  /*
+   * A filter map as a plain record, or {} — step JSON is not schema-checked,
+   * so the value here can be anything the API or an import wrote.
+   */
+  private static asAttributeRecord(value: unknown): Record<string, unknown> {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return {};
+    }
+
+    return value as Record<string, unknown>;
   }
 
   private static getDeclaredIdentifier(input: {
@@ -313,11 +521,31 @@ export default class MonitorStepResourceIdentity {
     this.mergeRefs({ target: input.refs, source: filterRefs });
   }
 
+  /*
+   * Every metric view config a step can carry. Each infra monitor type
+   * keeps its metric view config under its own key, so read them all —
+   * exactly the set MonitorStep's own metric-view-config resolver knows
+   * about.
+   */
+  private static getMetricViewConfigs(
+    stepData: NonNullable<MonitorStep["data"]>,
+  ): Array<MetricsViewConfig | undefined> {
+    return [
+      stepData.metricMonitor?.metricViewConfig,
+      stepData.hostMonitor?.metricViewConfig,
+      stepData.kubernetesMonitor?.metricViewConfig,
+      stepData.dockerMonitor?.metricViewConfig,
+      stepData.podmanMonitor?.metricViewConfig,
+      stepData.proxmoxMonitor?.metricViewConfig,
+      stepData.vmwareMonitor?.metricViewConfig,
+      stepData.cephMonitor?.metricViewConfig,
+      stepData.dockerSwarmMonitor?.metricViewConfig,
+      stepData.iotMonitor?.metricViewConfig,
+    ];
+  }
+
   /*
    * The attribute filters of every metric query on the step, merged.
-   * Each infra monitor type keeps its metric view config under its own
-   * key, so read them all — exactly the set MonitorStep's own
-   * metric-view-config resolver knows about.
    *
    * Values accumulate into an ARRAY per key rather than overwriting: a
    * step can hold several queries, and two of them filtering
@@ -330,20 +558,8 @@ export default class MonitorStepResourceIdentity {
   private static collectMetricFilterAttributes(input: {
     stepData: NonNullable<MonitorStep["data"]>;
   }): JSONObject {
-    const stepData: NonNullable<MonitorStep["data"]> = input.stepData;
-
-    const viewConfigs: Array<MetricsViewConfig | undefined> = [
-      stepData.metricMonitor?.metricViewConfig,
-      stepData.hostMonitor?.metricViewConfig,
-      stepData.kubernetesMonitor?.metricViewConfig,
-      stepData.dockerMonitor?.metricViewConfig,
-      stepData.podmanMonitor?.metricViewConfig,
-      stepData.proxmoxMonitor?.metricViewConfig,
-      stepData.vmwareMonitor?.metricViewConfig,
-      stepData.cephMonitor?.metricViewConfig,
-      stepData.dockerSwarmMonitor?.metricViewConfig,
-      stepData.iotMonitor?.metricViewConfig,
-    ];
+    const viewConfigs: Array<MetricsViewConfig | undefined> =
+      this.getMetricViewConfigs(input.stepData);
 
     const valuesByKey: Map<string, Array<string>> = new Map<
       string,
@@ -439,6 +655,8 @@ export default class MonitorStepResourceIdentity {
       iotFleetNames: [],
       serviceIds: [],
       serviceNames: [],
+      databaseServerIds: [],
+      databaseServerEndpoints: [],
     };
   }
 

package/Server/Utils/Monitor/PerSeriesResolutionRootCause.ts

@@ -0,0 +1,43 @@
+import Dictionary from "../../../Types/Dictionary";
+import { JSONObject } from "../../../Types/JSON";
+import MonitorCriteriaInstance from "../../../Types/Monitor/MonitorCriteriaInstance";
+import SeriesLabelDisplay from "../../../Types/Monitor/SeriesContext/SeriesLabelDisplay";
+
+/*
+ * Why one series' alert or incident was auto-resolved.
+ *
+ * In per-series mode a series that has recovered is resolved on a tick
+ * where other series can still be breaching. That tick's root cause
+ * describes the series that are still breaching, and it used to be
+ * written onto the recovered series' state timeline as-is — so node A's
+ * "resolved" email listed, under "Root Cause", the nodes that were still
+ * down. This names the series that recovered and the criteria it no
+ * longer satisfies instead.
+ */
+export default class PerSeriesResolutionRootCause {
+  public static build(input: {
+    seriesLabels: JSONObject | undefined;
+    createdCriteriaId: string | undefined;
+    criteriaInstancesById?: Dictionary<MonitorCriteriaInstance> | undefined;
+  }): string {
+    const seriesSummary: string = SeriesLabelDisplay.buildInlineSummary(
+      input.seriesLabels,
+    );
+
+    const criteriaName: string = input.createdCriteriaId
+      ? input.criteriaInstancesById?.[
+          input.createdCriteriaId
+        ]?.data?.name?.trim() || ""
+      : "";
+
+    const series: string = seriesSummary
+      ? `Series "${seriesSummary}"`
+      : "This series";
+
+    const criteria: string = criteriaName
+      ? `criteria "${criteriaName}"`
+      : "the criteria that raised it";
+
+    return `${series} no longer satisfies ${criteria}.`;
+  }
+}

package/Server/Utils/Monitor/SeriesResourceLabels.ts

@@ -1,4 +1,14 @@
 import { JSONObject } from "../../../Types/JSON";
+import ObjectID from "../../../Types/ObjectID";
+import {
+  DatabaseEndpoint,
+  canonicalizeDatabaseEndpoint,
+  formatDatabaseEndpoint,
+} from "../../../Types/DatabaseServer/DatabaseEndpoint";
+import {
+  DATABASE_SYSTEMS,
+  normalizeDatabaseSystem,
+} from "../../../Types/DatabaseServer/DatabaseSystem";
 
 /*
  * A grouped metric monitor (e.g. group-by `resource.host.name`) emits
@@ -155,6 +165,84 @@ export const IoTFleetNameLabelKeys: ReadonlyArray<string> = [
   "iot.fleet.name",
 ];
 
+/*
+ * Database identity rides the `oneuptime.database.server.id` stamp ingest
+ * adds to a database's own telemetry (collector / Database Agent receiver
+ * batches — see Telemetry.getAttributesForDatabaseServerIdAndName) and its
+ * ClickHouse `resource.`-prefixed twin, which the Database Agent also sets
+ * as an input resource attribute. Id keys only, on purpose: the
+ * `oneuptime.database.server.name` stamp is a display name ("PostgreSQL
+ * db.prod:5432"), which is neither unique per project (it drops the
+ * endpoint's `@cluster` qualifier, and the same namespace/workload can run
+ * in two clusters) nor stable (users rename databases). Resolving it would
+ * link an incident to — and let maintenance on one database silence — every
+ * same-named database. A monitor that should link its events to a database
+ * groups (or filters) by `oneuptime.database.server.id`.
+ *
+ * Unlike the host id stamp, the `resource.`-prefixed value can be typed by a
+ * user (the agent's DATABASE_SERVER_ID), so extractResourceRefs keeps only
+ * UUID-shaped values: a malformed one would make the primary-key lookup
+ * throw out of alert / incident creation.
+ */
+export const DatabaseServerIdLabelKeys: ReadonlyArray<string> = [
+  "resource.oneuptime.database.server.id",
+  "oneuptime.database.server.id",
+];
+
+/*
+ * The attributes that name a database by the ENDPOINT it listens on: the
+ * semconv `server.address` / `server.port` a DB client span, a `db.client.*`
+ * datapoint and a Database Agent batch all carry, plus the engine
+ * (`db.system.name`, legacy `db.system`) that supplies the default port
+ * semconv leaves out, and the Kubernetes namespace / cluster that
+ * canonicalization needs for cluster-local names.
+ *
+ * Read ONLY from a monitor's own configuration — an attribute FILTER on a
+ * metric or trace query (see MonitorStepResourceIdentity) — and resolved
+ * through the project's DatabaseServerEndpoint rows. Never from series
+ * labels, on purpose:
+ *
+ *   - `server.address` is the generic OTel peer attribute, set on every HTTP
+ *     client span too. A filter the user wrote is a deliberate statement of
+ *     which server a monitor watches; a group-by value is whatever peer a
+ *     series happened to call.
+ *   - Series identity also drives maintenance suppression
+ *     (MonitorMaintenanceSuppression), which matches databases by id only.
+ *     Linking a series by endpoint without suppressing it by endpoint is the
+ *     linked-but-not-silenced divergence the header of this file exists to
+ *     prevent.
+ *
+ * For the same first reason these keys are NOT resource-identity keys and are
+ * absent from AllResourceIdentityLabelKeys: a monitor script may legitimately
+ * record which server it measured.
+ */
+export const DatabaseServerAddressLabelKeys: ReadonlyArray<string> = [
+  "resource.server.address",
+  "server.address",
+];
+
+export const DatabaseServerPortLabelKeys: ReadonlyArray<string> = [
+  "resource.server.port",
+  "server.port",
+];
+
+export const DatabaseSystemLabelKeys: ReadonlyArray<string> = [
+  "resource.db.system.name",
+  "db.system.name",
+  "resource.db.system",
+  "db.system",
+];
+
+export const DatabaseKubernetesNamespaceLabelKeys: ReadonlyArray<string> = [
+  "resource.k8s.namespace.name",
+  "k8s.namespace.name",
+];
+
+export const DatabaseKubernetesClusterLabelKeys: ReadonlyArray<string> = [
+  "resource.k8s.cluster.name",
+  "k8s.cluster.name",
+];
+
 /*
  * Services come from OTel-ingested telemetry. The ingest pipeline
  * auto-creates a Service row keyed by `service.name`, so any series
@@ -211,6 +299,7 @@ export const AllResourceIdentityLabelKeys: ReadonlyArray<string> = [
   ...VMwareVCenterNameLabelKeys,
   ...CephClusterNameLabelKeys,
   ...IoTFleetNameLabelKeys,
+  ...DatabaseServerIdLabelKeys,
   ...ServiceIdLabelKeys,
   ...ServiceNameLabelKeys,
 ];
@@ -238,6 +327,16 @@ export interface SeriesResourceRefs {
   iotFleetNames: Array<string>;
   serviceIds: Array<string>;
   serviceNames: Array<string>;
+  // Id-only: see DatabaseServerIdLabelKeys for why there is no name list.
+  databaseServerIds: Array<string>;
+  /*
+   * Canonical endpoints ("db.prod:5432", formatDatabaseEndpoint) a monitor's
+   * configuration names — a probe Database Health / SQL Query target, or a
+   * `server.address` filter. Resolved to databaseServerIds through the
+   * project's DatabaseServerEndpoint rows. Always empty from series labels:
+   * see DatabaseServerAddressLabelKeys.
+   */
+  databaseServerEndpoints: Array<string>;
 }
 
 export default class SeriesResourceLabels {
@@ -324,6 +423,198 @@ export default class SeriesResourceLabels {
       ),
       serviceIds: this.collectLabelValues(seriesLabels, ServiceIdLabelKeys),
       serviceNames: this.collectLabelValues(seriesLabels, ServiceNameLabelKeys),
+      databaseServerIds: this.extractDatabaseServerIds(seriesLabels),
+      // Never from series labels — see DatabaseServerAddressLabelKeys.
+      databaseServerEndpoints: [],
+    };
+  }
+
+  /*
+   * The `oneuptime.database.server.id` values an attribute map carries, UUID
+   * shaped only (see DatabaseServerIdLabelKeys for why).
+   */
+  public static extractDatabaseServerIds(
+    attributes: JSONObject,
+  ): Array<string> {
+    return this.collectLabelValues(
+      attributes,
+      DatabaseServerIdLabelKeys,
+    ).filter((value: string): boolean => {
+      return ObjectID.isValidUUID(value);
+    });
+  }
+
+  /*
+   * The canonical database endpoint a (host, port, engine) triple names, as
+   * it is stored on DatabaseServerEndpoint rows — or null when it names no
+   * identifiable server.
+   *
+   * Canonicalized exactly as ingest canonicalizes what a client call saw
+   * (`canonicalizeDatabaseEndpoint`, purpose "client-call"), so the lookup is
+   * an exact string match: one host spelling, the engine's default port when
+   * none is given, Kubernetes service names expanded with the namespace, and
+   * cluster-local names qualified with the cluster when one is known.
+   * Loopback and host-relative names are null — "localhost:5432" is a
+   * different server for every caller, so it can never identify one row.
+   */
+  public static buildDatabaseEndpointRef(input: {
+    address: unknown;
+    port?: unknown;
+    system?: string | null | undefined;
+    kubernetesNamespace?: string | null | undefined;
+    kubernetesClusterName?: string | null | undefined;
+  }): string | null {
+    if (typeof input.address !== "string" || !input.address.trim()) {
+      return null;
+    }
+
+    const port: string | number | null =
+      typeof input.port === "number" || typeof input.port === "string"
+        ? input.port
+        : null;
+
+    const endpoint: DatabaseEndpoint | null = canonicalizeDatabaseEndpoint({
+      system: normalizeDatabaseSystem(input.system) || "",
+      address: input.address,
+      port: port,
+      caller: {
+        kubernetesNamespace: input.kubernetesNamespace || null,
+        kubernetesClusterName: input.kubernetesClusterName || null,
+        hostName: null,
+        isEphemeral: true,
+      },
+      purpose: "client-call",
+    });
+
+    return endpoint ? formatDatabaseEndpoint(endpoint) : null;
+  }
+
+  /*
+   * Every database endpoint ONE query's attribute filter names: each
+   * `server.address` value, with the port the filter gives, else the default
+   * port of the engine the filter (or, failing that, the metric's receiver
+   * prefix — `postgresql.backends` is PostgreSQL's) names.
+   *
+   * Takes one query's raw filter, not a merged map, because the port and the
+   * engine only mean something next to the address they were written with.
+   * Values may be strings, numbers or arrays of either; anything else (a
+   * Search or Includes matcher) names no single server and is skipped.
+   */
+  public static extractDatabaseEndpoints(input: {
+    attributes: Record<string, unknown> | null | undefined;
+    metricName?: string | null | undefined;
+  }): Array<string> {
+    const attributes: Record<string, unknown> =
+      input.attributes && typeof input.attributes === "object"
+        ? input.attributes
+        : {};
+
+    const addresses: Array<string> = this.collectScalarValues(
+      attributes,
+      DatabaseServerAddressLabelKeys,
+    );
+
+    if (addresses.length === 0) {
+      return [];
+    }
+
+    const ports: Array<string> = this.collectScalarValues(
+      attributes,
+      DatabaseServerPortLabelKeys,
+    );
+
+    const system: string | null =
+      this.collectScalarValues(attributes, DatabaseSystemLabelKeys)[0] ||
+      this.getDatabaseSystemFromMetricName(input.metricName);
+
+    const kubernetesNamespace: string | undefined = this.collectScalarValues(
+      attributes,
+      DatabaseKubernetesNamespaceLabelKeys,
+    )[0];
+
+    const kubernetesClusterName: string | undefined = this.collectScalarValues(
+      attributes,
+      DatabaseKubernetesClusterLabelKeys,
+    )[0];
+
+    const endpoints: Set<string> = new Set<string>();
+
+    for (const address of addresses) {
+      for (const port of ports.length > 0 ? ports : [null]) {
+        const endpoint: string | null = this.buildDatabaseEndpointRef({
+          address: address,
+          port: port,
+          system: system,
+          kubernetesNamespace: kubernetesNamespace,
+          kubernetesClusterName: kubernetesClusterName,
+        });
+
+        if (endpoint) {
+          endpoints.add(endpoint);
+        }
+      }
+    }
+
+    return Array.from(endpoints);
+  }
+
+  /*
+   * The engine whose collector receiver emits `metricName`, from the
+   * receivers' metric prefixes (`postgresql.`, `redis.`, ...). Null for
+   * anything else — `db.client.*` included, which every engine's clients
+   * emit alike.
+   */
+  private static getDatabaseSystemFromMetricName(
+    metricName: string | null | undefined,
+  ): string | null {
+    if (typeof metricName !== "string" || !metricName) {
+      return null;
+    }
+
+    const name: string = metricName.trim().toLowerCase();
+
+    for (const descriptor of DATABASE_SYSTEMS) {
+      for (const prefix of descriptor.receiverMetricPrefixes) {
+        if (name.startsWith(prefix)) {
+          return descriptor.system;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /*
+   * Like collectLabelValues, but a filter value may also be a number (a port
+   * typed into the query form) — stringified — and anything that is not a
+   * plain scalar is dropped rather than coerced into "[object Object]".
+   */
+  private static collectScalarValues(
+    attributes: Record<string, unknown>,
+    keys: ReadonlyArray<string>,
+  ): Array<string> {
+    const found: Set<string> = new Set<string>();
+
+    const add: (value: unknown) => void = (value: unknown): void => {
+      if (typeof value === "string" && value.trim().length > 0) {
+        found.add(value.trim());
+      } else if (typeof value === "number" && Number.isFinite(value)) {
+        found.add(String(value));
+      }
     };
+
+    for (const key of keys) {
+      const value: unknown = attributes[key];
+
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          add(item);
+        }
+      } else {
+        add(value);
+      }
+    }
+
+    return Array.from(found);
   }
 }