@oneuptime/common 12.0.25 → 12.0.27

package/Types/Monitor/DockerAlertTemplates.ts

@@ -30,6 +30,22 @@ export interface DockerAlertTemplate {
   getMonitorStep: (args: DockerAlertTemplateArgs) => MonitorStep;
 }
 
+/*
+ * Filter contract: the Docker agent stamps container identity as OTLP
+ * RESOURCE attributes, so ClickHouse stores them `resource.`-prefixed:
+ * `resource.container.name`, `resource.container.image.name`,
+ * `resource.container.runtime` ("docker") 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.
+ *
+ * NOTE: this is `resource.`-prefixed, unlike Docker Swarm, whose
+ * docker_stats receiver keeps container identity in DATAPOINT labels
+ * (plain `container.name`).
+ */
+
 export function buildDockerMonitorStep(args: {
   dockerMonitor: MonitorStepDockerMonitor;
   offlineCriteriaInstance: MonitorCriteriaInstance;
@@ -184,6 +200,7 @@ export function buildDockerMonitorConfig(args: {
   rollingTime: RollingTime;
   aggregationType: MetricsAggregationType;
   attributes?: Record<string, string>;
+  groupByAttributeKey?: string | undefined;
 }): MonitorStepDockerMonitor {
   return {
     hostIdentifier: args.hostIdentifier,
@@ -205,6 +222,9 @@ export function buildDockerMonitorConfig(args: {
               aggegationType: args.aggregationType,
               aggregateBy: {},
             },
+            ...(args.groupByAttributeKey
+              ? { groupByAttributeKeys: [args.groupByAttributeKey] }
+              : {}),
           },
         },
       ],
@@ -219,7 +239,8 @@ export function buildDockerMonitorConfig(args: {
 const highCpuTemplate: DockerAlertTemplate = {
   id: "docker-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: DockerAlertTemplateArgs): MonitorStep => {
@@ -232,10 +253,12 @@ const highCpuTemplate: DockerAlertTemplate = {
         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: buildDockerOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -264,7 +287,8 @@ const highCpuTemplate: DockerAlertTemplate = {
 const highMemoryTemplate: DockerAlertTemplate = {
   id: "docker-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: DockerAlertTemplateArgs): MonitorStep => {
@@ -277,10 +301,12 @@ const highMemoryTemplate: DockerAlertTemplate = {
         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: buildDockerOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -310,7 +336,7 @@ const containerRestartLoopTemplate: DockerAlertTemplate = {
   id: "docker-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: DockerAlertTemplateArgs): MonitorStep => {
@@ -323,6 +349,7 @@ const containerRestartLoopTemplate: DockerAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Max,
+        groupByAttributeKey: "resource.container.name",
       }),
       offlineCriteriaInstance: buildDockerOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -352,7 +379,7 @@ const highCpuThrottlingTemplate: DockerAlertTemplate = {
   id: "docker-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: DockerAlertTemplateArgs): MonitorStep => {
@@ -365,10 +392,12 @@ const highCpuThrottlingTemplate: DockerAlertTemplate = {
         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: buildDockerOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -398,7 +427,7 @@ const highProcessCountTemplate: DockerAlertTemplate = {
   id: "docker-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: DockerAlertTemplateArgs): MonitorStep => {
@@ -411,6 +440,7 @@ const highProcessCountTemplate: DockerAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past5Minutes,
         aggregationType: MetricsAggregationType.Max,
+        groupByAttributeKey: "resource.container.name",
       }),
       offlineCriteriaInstance: buildDockerOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -440,7 +470,7 @@ const containerUptimeTemplate: DockerAlertTemplate = {
   id: "docker-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: DockerAlertTemplateArgs): MonitorStep => {
@@ -453,6 +483,7 @@ const containerUptimeTemplate: DockerAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past1Minute,
         aggregationType: MetricsAggregationType.Min,
+        groupByAttributeKey: "resource.container.name",
       }),
       offlineCriteriaInstance: buildDockerOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,

package/Types/Monitor/HostAlertTemplates.ts

@@ -30,6 +30,25 @@ export interface HostAlertTemplate {
   getMonitorStep: (args: HostAlertTemplateArgs) => MonitorStep;
 }
 
+/*
+ * Filter contract: a host monitor is already scoped to ONE host — the
+ * worker adds `resource.host.name` from the step's hostIdentifier — so
+ * host-scalar metrics (CPU utilization, memory utilization, load average,
+ * process count) stay UNGROUPED: there is exactly one series per host and
+ * grouping would buy nothing.
+ *
+ * Metrics that are per-entity WITHIN the host are grouped, because the
+ * hostmetrics receiver partitions them by unprefixed DATAPOINT labels
+ * (never `resource.`-prefixed):
+ *
+ *   - `system.filesystem.*` -> `mountpoint` (also `device`, `state`)
+ *   - `system.disk.*` / `system.network.*` -> `device` (also `direction`)
+ *
+ * Without a group-by, one full mount raises a single incident for the
+ * whole host and every other mount that fills up afterwards is silenced
+ * for as long as that incident stays open.
+ */
+
 export function buildHostMonitorStep(args: {
   hostMonitor: MonitorStepHostMonitor;
   offlineCriteriaInstance: MonitorCriteriaInstance;
@@ -184,6 +203,7 @@ export function buildHostMonitorConfig(args: {
   rollingTime: RollingTime;
   aggregationType: MetricsAggregationType;
   attributes?: Record<string, string>;
+  groupByAttributeKey?: string | undefined;
 }): MonitorStepHostMonitor {
   return {
     hostIdentifier: args.hostIdentifier,
@@ -204,6 +224,9 @@ export function buildHostMonitorConfig(args: {
               aggegationType: args.aggregationType,
               aggregateBy: {},
             },
+            ...(args.groupByAttributeKey
+              ? { groupByAttributeKeys: [args.groupByAttributeKey] }
+              : {}),
           },
         },
       ],
@@ -302,7 +325,8 @@ const highMemoryTemplate: HostAlertTemplate = {
 const highFilesystemUsageTemplate: HostAlertTemplate = {
   id: "host-high-filesystem",
   name: "High Filesystem Usage",
-  description: "Alert when host filesystem utilization exceeds 90%.",
+  description:
+    "Alert when host filesystem utilization exceeds 90%. One alert per mountpoint.",
   category: "Resource",
   severity: "Critical",
   getMonitorStep: (args: HostAlertTemplateArgs): MonitorStep => {
@@ -315,10 +339,14 @@ const highFilesystemUsageTemplate: HostAlertTemplate = {
         metricAlias,
         rollingTime: RollingTime.Past5Minutes,
         /*
-         * Use Max so a single full filesystem trips the threshold instead of
-         * being diluted by averaging across multiple mounted filesystems.
+         * Max WITHIN each mountpoint's series: the peak utilization that
+         * mount reached during the window. Grouping by `mountpoint` already
+         * keeps mounts from being averaged together, and gives one incident
+         * per mount so a second mount filling up is not silenced by the
+         * first one's open incident.
          */
         aggregationType: MetricsAggregationType.Max,
+        groupByAttributeKey: "mountpoint",
       }),
       offlineCriteriaInstance: buildHostOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,

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;
 }