@oneuptime/common 12.0.25 → 12.0.26

package/Types/Monitor/KubernetesAlertTemplates.ts

@@ -182,6 +182,29 @@ export function buildOnlineCriteriaInstance(args: {
   return instance;
 }
 
+/**
+ * Build a single-query monitor config.
+ *
+ * `groupByAttributeKey` makes the monitor PER-SERIES: the worker splits
+ * the metric by that attribute and every group is evaluated — and paged —
+ * on its own, so a cluster of 200 pods raises one incident per unhealthy
+ * pod rather than one incident for the whole cluster that then dedupes
+ * every later pod away. Omitting it keeps the monitor whole-cluster.
+ *
+ * Group by an object's own name whenever the metric is genuinely
+ * PER-OBJECT (per node, per pod, per deployment, ...). Leave it off for
+ * cluster-scalar signals — etcd leadership, API server throttling,
+ * scheduler backlog — where there is exactly one value for the cluster
+ * and splitting it would invent series that do not exist.
+ *
+ * The key is the ClickHouse-stored attribute name, which carries the
+ * `resource.` prefix for OTel resource attributes (see
+ * OtelMetricsIngestService — resource attributes are stamped with
+ * `prefixKeysWithString: "resource"`). So node grouping is
+ * `resource.k8s.node.name`, not the bare `k8s.node.name`; the bare key
+ * matches nothing and collapses the whole fleet into one mislabeled
+ * series that still renders and still alerts.
+ */
 export function buildKubernetesMonitorConfig(args: {
   clusterIdentifier: string;
   metricName: string;
@@ -190,6 +213,7 @@ export function buildKubernetesMonitorConfig(args: {
   rollingTime: RollingTime;
   aggregationType: MetricsAggregationType;
   attributes?: Record<string, string>;
+  groupByAttributeKey?: string | undefined;
 }): MonitorStepKubernetesMonitor {
   return {
     clusterIdentifier: args.clusterIdentifier,
@@ -212,6 +236,9 @@ export function buildKubernetesMonitorConfig(args: {
               aggegationType: args.aggregationType,
               aggregateBy: {},
             },
+            ...(args.groupByAttributeKey
+              ? { groupByAttributeKeys: [args.groupByAttributeKey] }
+              : {}),
           },
         },
       ],
@@ -346,6 +373,13 @@ const crashLoopBackOffTemplate: KubernetesAlertTemplate = {
         resourceScope: KubernetesResourceScope.Cluster,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Max,
+        /*
+         * Per pod: restarts are a property of one pod's containers, so a
+         * crash-looping pod must page on its own rather than dedupe behind
+         * whichever pod in the cluster crashed first. Max over the window
+         * therefore becomes "the worst container in THIS pod".
+         */
+        groupByAttributeKey: "resource.k8s.pod.name",
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -390,6 +424,22 @@ const podPendingTemplate: KubernetesAlertTemplate = {
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Sum,
         attributes: { "resource.k8s.pod.phase": "Pending" },
+        /*
+         * Deliberately NOT grouped, unlike the other pod-level templates.
+         *
+         * This is a cluster-wide COUNT of unschedulable pods (Cluster
+         * scope, Sum, "Count > 0"), i.e. a statement about the cluster's
+         * scheduling capacity rather than about any one pod's health — the
+         * same signal as k8s-scheduler-backlog, seen from the pod side.
+         *
+         * Grouping it by `resource.k8s.pod.name` would fan out per pod
+         * name, and pending pod names are ephemeral: a stuck rollout burns
+         * a new replicaset-hash-suffixed name per attempt, so every retry
+         * would open a fresh incident and resolve it again the moment the
+         * name changed. That is an alert storm keyed on an identity that
+         * does not persist, which is the opposite of what per-series
+         * grouping is for (durable entities: nodes, deployments, jobs).
+         */
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -433,6 +483,12 @@ const nodeNotReadyTemplate: KubernetesAlertTemplate = {
         resourceScope: KubernetesResourceScope.Node,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Min,
+        /*
+         * Per node: one incident per NotReady node. Ungrouped, the Min
+         * across the fleet is 0 as soon as ANY node is down, and the
+         * second node to fail dedupes behind the first one's incident.
+         */
+        groupByAttributeKey: "resource.k8s.node.name",
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -584,6 +640,14 @@ const deploymentReplicaMismatchTemplate: KubernetesAlertTemplate = {
         resourceScope: KubernetesResourceScope.Workload,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Max,
+        /*
+         * Per deployment: a stuck rollout is a property of one Deployment
+         * object, and the incident copy already names the deployment. The
+         * k8s_cluster receiver stamps `k8s.deployment.name` on this metric
+         * (the worker reads `resource.k8s.deployment.name` back off these
+         * rows to build the affected-resource breakdown).
+         */
+        groupByAttributeKey: "resource.k8s.deployment.name",
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -626,6 +690,13 @@ const jobFailuresTemplate: KubernetesAlertTemplate = {
         resourceScope: KubernetesResourceScope.Workload,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Max,
+        /*
+         * Per Job object — one failing Job must not hide the next one.
+         * Jobs are short-lived: when a Job is cleaned up its series stops
+         * arriving and the per-series pass auto-resolves that Job's alert
+         * by absence, which is the behaviour we want here.
+         */
+        groupByAttributeKey: "resource.k8s.job.name",
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -669,6 +740,11 @@ const etcdNoLeaderTemplate: KubernetesAlertTemplate = {
         resourceScope: KubernetesResourceScope.Cluster,
         rollingTime: RollingTime.Past1Minute,
         aggregationType: MetricsAggregationType.Min,
+        /*
+         * Ungrouped: leadership is a property of the etcd cluster as a
+         * whole, not of any one object. "No leader" is one cluster-scalar
+         * fact and belongs in one incident.
+         */
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -712,6 +788,11 @@ const apiServerThrottlingTemplate: KubernetesAlertTemplate = {
         resourceScope: KubernetesResourceScope.Cluster,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Sum,
+        /*
+         * Ungrouped: this is the control plane's aggregate throttling
+         * rate. Splitting it would need a per-apiserver-instance identity
+         * that this metric does not carry in the shipped agent config.
+         */
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -755,6 +836,10 @@ const schedulerBacklogTemplate: KubernetesAlertTemplate = {
         resourceScope: KubernetesResourceScope.Cluster,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Avg,
+        /*
+         * Ungrouped: a scheduler queue depth is one number for the
+         * cluster. There is no per-object series to split it into.
+         */
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -797,6 +882,13 @@ const highDiskUsageTemplate: KubernetesAlertTemplate = {
         resourceScope: KubernetesResourceScope.Node,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Avg,
+        /*
+         * Per node: filesystem usage is per node (kubeletstats reports the
+         * node's filesystem), and disk fills one node at a time. Ungrouped,
+         * the Avg across the fleet dilutes a single full node into the
+         * fleet mean and the alert never fires.
+         */
+        groupByAttributeKey: "resource.k8s.node.name",
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -840,6 +932,12 @@ const daemonSetUnavailableTemplate: KubernetesAlertTemplate = {
         resourceScope: KubernetesResourceScope.Workload,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Max,
+        /*
+         * Per DaemonSet object: the incident names the DaemonSet, so each
+         * one has to own its own alert instead of dedupeing behind
+         * whichever DaemonSet in the cluster misscheduled first.
+         */
+        groupByAttributeKey: "resource.k8s.daemonset.name",
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,

package/Types/Monitor/MonitorStep.ts

@@ -79,6 +79,7 @@ import MonitorStepIoTMonitor, {
   MonitorStepIoTMonitorUtil,
 } from "./MonitorStepIoTMonitor";
 import MetricsViewConfig from "../Metrics/MetricsViewConfig";
+import MetricQueryConfigData from "../Metrics/MetricQueryConfigData";
 import Zod, { ZodSchema } from "../../Utils/Schema/Zod";
 
 /*
@@ -389,6 +390,54 @@ export default class MonitorStep extends DatabaseProperty {
     );
   }
 
+  /**
+   * The union of `groupByAttributeKeys` across every metric query config
+   * on this step — i.e. the attributes the monitor is grouped by.
+   *
+   * This is the single source of truth for "is this monitor grouped?".
+   * The telemetry worker uses it to decide whether to build a
+   * `seriesBreakdown`, and the criteria evaluator uses it to decide
+   * whether a criteria is *meant* to fan out one alert/incident per
+   * series. Those two answers must never disagree: when they did, a
+   * grouped monitor that produced no per-series match silently fell
+   * back to a single whole-monitor alert whose dedupe key carries no
+   * series, and every host after the first was skipped for as long as
+   * that alert stayed open.
+   */
+  public static getGroupByAttributeKeys(
+    monitorStep: MonitorStep | undefined,
+  ): Array<string> {
+    return MonitorStep.getGroupByAttributeKeysFromQueryConfigs(
+      MonitorStep.getMetricsViewConfig(monitorStep)?.queryConfigs || [],
+    );
+  }
+
+  /**
+   * The query-config-level half of `getGroupByAttributeKeys`, for the
+   * telemetry worker which already holds the configs and never
+   * reconstructs the step. Per-series alerting needs a consistent key
+   * set across queries so formula series line up — otherwise `a + b`
+   * would split differently for `a` and for `b` and the per-series
+   * formula evaluation would not align — hence the union rather than
+   * per-query keys.
+   */
+  public static getGroupByAttributeKeysFromQueryConfigs(
+    queryConfigs: Array<MetricQueryConfigData>,
+  ): Array<string> {
+    const keys: Set<string> = new Set<string>();
+
+    for (const queryConfig of queryConfigs) {
+      for (const key of queryConfig?.metricQueryData?.groupByAttributeKeys ||
+        []) {
+        if (key) {
+          keys.add(key);
+        }
+      }
+    }
+
+    return Array.from(keys);
+  }
+
   public get id(): ObjectID {
     return new ObjectID(this.data?.id as string);
   }

package/Types/Monitor/PodmanAlertTemplates.ts

@@ -30,6 +30,18 @@ export interface PodmanAlertTemplate {
   getMonitorStep: (args: PodmanAlertTemplateArgs) => MonitorStep;
 }
 
+/*
+ * Filter contract: the Podman agent stamps container identity as OTLP
+ * RESOURCE attributes, so ClickHouse stores them `resource.`-prefixed:
+ * `resource.container.name`, `resource.container.image.name`,
+ * `resource.container.runtime` ("podman") and `resource.host.name`. The
+ * worker adds the host scope (`resource.host.name` from hostIdentifier)
+ * and the runtime filter itself. Every template groups by
+ * `resource.container.name` so each container on the host is evaluated
+ * independently — one incident per container instead of one incident for
+ * the whole host, where the busiest container silences every other one.
+ */
+
 export function buildPodmanMonitorStep(args: {
   podmanMonitor: MonitorStepPodmanMonitor;
   offlineCriteriaInstance: MonitorCriteriaInstance;
@@ -184,6 +196,7 @@ export function buildPodmanMonitorConfig(args: {
   rollingTime: RollingTime;
   aggregationType: MetricsAggregationType;
   attributes?: Record<string, string>;
+  groupByAttributeKey?: string | undefined;
 }): MonitorStepPodmanMonitor {
   return {
     hostIdentifier: args.hostIdentifier,
@@ -205,6 +218,9 @@ export function buildPodmanMonitorConfig(args: {
               aggegationType: args.aggregationType,
               aggregateBy: {},
             },
+            ...(args.groupByAttributeKey
+              ? { groupByAttributeKeys: [args.groupByAttributeKey] }
+              : {}),
           },
         },
       ],
@@ -219,7 +235,8 @@ export function buildPodmanMonitorConfig(args: {
 const highCpuTemplate: PodmanAlertTemplate = {
   id: "podman-high-cpu",
   name: "High Container CPU Usage",
-  description: "Alert when container CPU usage exceeds 80% sustained.",
+  description:
+    "Alert when container CPU usage exceeds 80% sustained. One alert per container.",
   category: "Resource",
   severity: "Warning",
   getMonitorStep: (args: PodmanAlertTemplateArgs): MonitorStep => {
@@ -232,10 +249,12 @@ const highCpuTemplate: PodmanAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past5Minutes,
         /*
-         * Use Max so a single hot container trips the threshold instead of
-         * being diluted by idle containers on the host.
+         * Max WITHIN each container's series: any scrape in the window over
+         * the threshold trips that container. Grouping by container name
+         * already keeps a hot container from being diluted by idle ones.
          */
         aggregationType: MetricsAggregationType.Max,
+        groupByAttributeKey: "resource.container.name",
       }),
       offlineCriteriaInstance: buildPodmanOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -264,7 +283,8 @@ const highCpuTemplate: PodmanAlertTemplate = {
 const highMemoryTemplate: PodmanAlertTemplate = {
   id: "podman-high-memory",
   name: "High Container Memory Usage",
-  description: "Alert when container memory usage exceeds 85% of its limit.",
+  description:
+    "Alert when container memory usage exceeds 85% of its limit. One alert per container.",
   category: "Resource",
   severity: "Warning",
   getMonitorStep: (args: PodmanAlertTemplateArgs): MonitorStep => {
@@ -277,10 +297,12 @@ const highMemoryTemplate: PodmanAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past5Minutes,
         /*
-         * Use Max so a single container breaching its limit trips the
-         * threshold instead of being diluted by idle containers.
+         * Max WITHIN each container's series: any scrape in the window over
+         * the limit trips that container. Grouping by container name already
+         * keeps a container at its limit from being diluted by idle ones.
          */
         aggregationType: MetricsAggregationType.Max,
+        groupByAttributeKey: "resource.container.name",
       }),
       offlineCriteriaInstance: buildPodmanOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -310,7 +332,7 @@ const containerRestartLoopTemplate: PodmanAlertTemplate = {
   id: "podman-restart-loop",
   name: "Container Restart Loop",
   description:
-    "Alert when a container has restarted more than 5 times, indicating a crash loop.",
+    "Alert when a container has restarted more than 5 times, indicating a crash loop. One alert per container.",
   category: "Container",
   severity: "Critical",
   getMonitorStep: (args: PodmanAlertTemplateArgs): MonitorStep => {
@@ -323,6 +345,7 @@ const containerRestartLoopTemplate: PodmanAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Max,
+        groupByAttributeKey: "resource.container.name",
       }),
       offlineCriteriaInstance: buildPodmanOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -352,7 +375,7 @@ const highCpuThrottlingTemplate: PodmanAlertTemplate = {
   id: "podman-cpu-throttling",
   name: "Container CPU Throttling",
   description:
-    "Alert when a container is being CPU-throttled, indicating it needs more CPU resources.",
+    "Alert when a container is being CPU-throttled, indicating it needs more CPU resources. One alert per container.",
   category: "Resource",
   severity: "Warning",
   getMonitorStep: (args: PodmanAlertTemplateArgs): MonitorStep => {
@@ -365,10 +388,12 @@ const highCpuThrottlingTemplate: PodmanAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past5Minutes,
         /*
-         * Use Max so a single throttled container trips the threshold,
-         * rather than summing throttled time across all containers.
+         * Max WITHIN each container's series, so throttled time is never
+         * summed across containers — grouping by container name attributes
+         * the throttling to the container that actually suffered it.
          */
         aggregationType: MetricsAggregationType.Max,
+        groupByAttributeKey: "resource.container.name",
       }),
       offlineCriteriaInstance: buildPodmanOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -398,7 +423,7 @@ const highProcessCountTemplate: PodmanAlertTemplate = {
   id: "podman-high-pids",
   name: "High Container Process Count",
   description:
-    "Alert when a container has an unusually high number of processes, which may indicate a fork bomb or resource leak.",
+    "Alert when a container has an unusually high number of processes, which may indicate a fork bomb or resource leak. One alert per container.",
   category: "Container",
   severity: "Warning",
   getMonitorStep: (args: PodmanAlertTemplateArgs): MonitorStep => {
@@ -411,6 +436,7 @@ const highProcessCountTemplate: PodmanAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Max,
+        groupByAttributeKey: "resource.container.name",
       }),
       offlineCriteriaInstance: buildPodmanOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -440,7 +466,7 @@ const containerUptimeTemplate: PodmanAlertTemplate = {
   id: "podman-container-down",
   name: "Container Down (Low Uptime)",
   description:
-    "Alert when a container's uptime drops to zero, indicating it has stopped or crashed.",
+    "Alert when a container's uptime drops to zero, indicating it has stopped or crashed. One alert per container.",
   category: "Container",
   severity: "Critical",
   getMonitorStep: (args: PodmanAlertTemplateArgs): MonitorStep => {
@@ -453,6 +479,7 @@ const containerUptimeTemplate: PodmanAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past1Minute,
         aggregationType: MetricsAggregationType.Min,
+        groupByAttributeKey: "resource.container.name",
       }),
       offlineCriteriaInstance: buildPodmanOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,

package/Types/Monitor/SnmpMonitor/CdpNeighbor.ts

@@ -10,4 +10,18 @@ export default interface CdpNeighbor {
   remoteDeviceId?: string | undefined;
   remotePortId?: string | undefined;
   remotePlatform?: string | undefined;
+  /*
+   * The address the neighbor advertises for itself (cdpCacheAddress, kept
+   * only when cdpCacheAddressType says it is an IP). Optional because the
+   * column is frequently empty and older payloads predate it entirely.
+   *
+   * Two things depend on it. It is a match key: a device we already manage
+   * BY ADDRESS — imported from a subnet sweep, so its hostname is an IP and
+   * its name is something else entirely — used to be drawn as a stranger
+   * because nothing the neighbor advertised looked like its name. And it is
+   * the one field that makes an unmanaged peer actionable: monitoring
+   * anything needs an address, and without this the map knows a device's
+   * make and model but not where it lives.
+   */
+  remoteIpAddress?: string | undefined;
 }

package/Types/Monitor/SnmpMonitor/LldpNeighbor.ts

@@ -9,4 +9,15 @@ export default interface LldpNeighbor {
   remoteChassisId?: string | undefined;
   remotePortId?: string | undefined;
   remoteSysName?: string | undefined;
+  /*
+   * The neighbor's management address, joined in from lldpRemManAddrTable
+   * (a separate table whose index carries the address). Optional: plenty of
+   * agents do not implement it, an IPv6-only entry is skipped, and older
+   * payloads predate the column.
+   *
+   * See CdpNeighbor.remoteIpAddress for why it is worth the extra walk — it
+   * matches devices we manage by address, and it is what turns an unmanaged
+   * peer on the map into something that can actually be monitored.
+   */
+  remoteIpAddress?: string | undefined;
 }

package/Types/Monitor/SnmpMonitor/NetworkTopology.ts

@@ -108,10 +108,17 @@ export interface NetworkTopologyNode {
   // For unmanaged CDP peers this carries the reported platform string.
   deviceModel?: string | undefined;
   /*
-   * Endpoint identity (endpoint nodes only), all best-effort: MAC from the
-   * FDB, IP from the ARP join, classification from OUI/heuristics (e.g.
-   * "pos-terminal", "camera", "printer"), VLAN from the FDB entry that
-   * learned the MAC. Optional so older payloads stay valid.
+   * Endpoint identity, all best-effort: MAC from the FDB, IP from the ARP
+   * join, classification from OUI/heuristics (e.g. "pos-terminal",
+   * "camera", "printer"), VLAN from the FDB entry that learned the MAC.
+   * Optional so older payloads stay valid.
+   *
+   * `ipAddress` is the exception to "endpoint nodes only": an UNMANAGED
+   * peer carries it too, from the management address its neighbours
+   * advertise for it (CDP cdpCacheAddress / LLDP lldpRemManAddrTable). It
+   * is the field that makes such a peer actionable rather than merely
+   * visible — nothing can be monitored without an address — so a reader
+   * must not assume a node with an ipAddress is an endpoint.
    */
   macAddress?: string | undefined;
   ipAddress?: string | undefined;

package/Types/NetworkAutomation/RuleRunResult.ts

@@ -93,8 +93,30 @@ export interface AutoImportRuleRunResult {
   // Matched hosts whose create threw. Logged server-side, never fatal.
   devicesFailed: number;
   /*
-   * True when the run stopped at the DEVICE cap with matched hosts left
-   * over. Running again continues: already-imported hosts are skipped.
+   * Active Network Device monitors a dry run predicts it would create from
+   * the rule's selected Monitor Template. Always zero on a real run: real
+   * work is counted by monitorsCreated / monitorsFailed instead.
+   */
+  monitorsWouldCreate: number;
+  // Active Network Device monitors actually created and linked to a template.
+  monitorsCreated: number;
+  /*
+   * Matched devices left alone because a Network Device monitor already
+   * watches them. Existing manual monitors count too: automation must never
+   * add a duplicate simply because it did not create the first one.
+   */
+  monitorsSkippedAlreadyExisting: number;
+  /*
+   * Matched hosts that can become inventory records but cannot be backed by a
+   * Network Device monitor, such as a ping-only discovery result.
+   */
+  monitorsSkippedUnsupportedHost: number;
+  // Monitor creates that failed after the device was available.
+  monitorsFailed: number;
+  /*
+   * True when the run stopped at the device-create or monitor-create cap
+   * with work left over. Running again continues from idempotent inventory
+   * and provisioning keys.
    */
   isTruncated: boolean;
   /*
@@ -132,7 +154,163 @@ function readCount(json: JSONObject, key: string): number {
   return value;
 }
 
+function hosts(count: number): string {
+  return `${count} ${count === 1 ? "host" : "hosts"}`;
+}
+
+function activeMonitors(count: number): string {
+  return `${count} active Network Device ${
+    count === 1 ? "monitor" : "monitors"
+  }`;
+}
+
 export class RuleRunResultUtil {
+  /*
+   * The sentences the auto-import report shows. A run that imported nothing is
+   * the common case once a rule has been run, and "0 imported" with no reason
+   * reads as a broken button — so every bucket the server counted is reported
+   * only when it happened.
+   *
+   * It lives here rather than beside the browser modal so the App test suite,
+   * which has no react in its import graph, can exercise the wording without
+   * pulling in the component's react dependency.
+   */
+  public static describeAutoImportRun(result: AutoImportRuleRunResult): string {
+    const lines: Array<string> = [];
+
+    if (result.isDryRun) {
+      /*
+       * A dry run creates nothing, so devicesCreated is always zero. What a
+       * real run would attempt is matched minus already-registered — the
+       * server reports it exactly this way (see the engine's dry-run branch).
+       */
+      const wouldImport: number = Math.max(
+        result.hostsMatched - result.hostsSkippedAlreadyRegistered,
+        0,
+      );
+
+      if (wouldImport > 0) {
+        lines.push(
+          `This rule would import ${hosts(
+            wouldImport,
+          )} as network devices. Nothing was written — this was a dry run.`,
+        );
+      } else {
+        lines.push(
+          `This rule would import nothing. It matched ${hosts(
+            result.hostsMatched,
+          )} out of the ${hosts(
+            result.hostsEvaluated,
+          )} discovered hosts it looked at.`,
+        );
+      }
+    } else if (result.devicesCreated > 0) {
+      lines.push(
+        `Imported ${hosts(result.devicesCreated)} as network devices.`,
+      );
+    } else {
+      lines.push(
+        `No devices were imported. This rule matched ${hosts(
+          result.hostsMatched,
+        )} out of the ${hosts(
+          result.hostsEvaluated,
+        )} discovered hosts it looked at.`,
+      );
+    }
+
+    /*
+     * Device import and active-monitor provisioning are separate outcomes. A
+     * monitor can fail after its inventory record was safely created, and a
+     * dry run predicts monitor work without claiming anything was written.
+     */
+    if (result.isDryRun && result.monitorsWouldCreate > 0) {
+      lines.push(
+        `It would also create ${activeMonitors(
+          result.monitorsWouldCreate,
+        )} from the selected Monitor Template.`,
+      );
+    } else if (!result.isDryRun && result.monitorsCreated > 0) {
+      lines.push(
+        `Created ${activeMonitors(
+          result.monitorsCreated,
+        )} from the selected Monitor Template.`,
+      );
+    }
+
+    if (result.monitorsSkippedAlreadyExisting > 0) {
+      const skippedRequestedMonitors: string = `${
+        result.monitorsSkippedAlreadyExisting
+      } requested active Network Device ${
+        result.monitorsSkippedAlreadyExisting === 1 ? "monitor" : "monitors"
+      }`;
+      lines.push(
+        `${skippedRequestedMonitors} ${
+          result.monitorsSkippedAlreadyExisting === 1 ? "was" : "were"
+        } skipped because the device already had the requested automatic monitor or a manually configured Network Device monitor.`,
+      );
+    }
+
+    if (result.monitorsSkippedUnsupportedHost > 0) {
+      lines.push(
+        `${activeMonitors(
+          result.monitorsSkippedUnsupportedHost,
+        )} could not be provisioned because the discovery result was not SNMP-capable (for example, a ping-only host).`,
+      );
+    }
+
+    if (result.monitorsFailed > 0) {
+      lines.push(
+        `${activeMonitors(
+          result.monitorsFailed,
+        )} could not be created. Their network devices remain imported; check the server logs for the reason.`,
+      );
+    }
+
+    if (result.hostsExcluded > 0) {
+      lines.push(`An exclusion rule vetoed ${hosts(result.hostsExcluded)}.`);
+    }
+
+    if (result.hostsSkippedAlreadyRegistered > 0) {
+      lines.push(
+        `${hosts(
+          result.hostsSkippedAlreadyRegistered,
+        )} already had network devices at those addresses, so no duplicate device records were imported.`,
+      );
+    }
+
+    if (result.devicesFailed > 0) {
+      lines.push(
+        `${hosts(
+          result.devicesFailed,
+        )} could not be imported. Check the server logs for the reason.`,
+      );
+    }
+
+    /*
+     * Two different caps, two different truths. The device cap resumes:
+     * re-running skips what is already imported and continues. The scan cap
+     * does NOT: a re-run re-reads the same newest scans, so promising "run
+     * again to continue" there would send the operator in a circle.
+     */
+    if (result.isTruncated && !result.isDryRun) {
+      lines.push(
+        "Stopped at the run cap — run again to continue; already-imported hosts are skipped.",
+      );
+    } else if (result.isTruncated) {
+      lines.push(
+        "Stopped counting at the run cap — a real run is bounded by the same device-import and active-monitor creation limits.",
+      );
+    }
+
+    if (result.hasMoreScans) {
+      lines.push(
+        "Only the newest 100 completed scans were read — hosts that appear only in older scans were not evaluated by this run.",
+      );
+    }
+
+    return lines.join(" ");
+  }
+
   public static parseSiteAssignmentRuleRunResult(
     json: JSONObject | undefined | null,
   ): SiteAssignmentRuleRunResult {
@@ -196,6 +374,17 @@ export class RuleRunResultUtil {
       ),
       devicesCreated: readCount(source, "devicesCreated"),
       devicesFailed: readCount(source, "devicesFailed"),
+      monitorsWouldCreate: readCount(source, "monitorsWouldCreate"),
+      monitorsCreated: readCount(source, "monitorsCreated"),
+      monitorsSkippedAlreadyExisting: readCount(
+        source,
+        "monitorsSkippedAlreadyExisting",
+      ),
+      monitorsSkippedUnsupportedHost: readCount(
+        source,
+        "monitorsSkippedUnsupportedHost",
+      ),
+      monitorsFailed: readCount(source, "monitorsFailed"),
       isTruncated: source["isTruncated"] === true,
       hasMoreScans: source["hasMoreScans"] === true,
       isDryRun: source["isDryRun"] === true,