@oneuptime/common 14.0.3 → 14.0.5

package/Types/Monitor/KubernetesAlertTemplates.ts

@@ -289,6 +289,14 @@ export function buildKubernetesRatioMonitorConfig(args: {
    * the operand ALIASES, not the metric names.
    */
   formula?: string | undefined;
+  /*
+   * The formula result's display unit. Defaults to "%", which is right for
+   * every ratio. A `formula` that is not a percentage — the deployment
+   * replica shortfall is `desired - available`, a pod count — passes ""
+   * so the alert reads "2", not "2%". Display only: the unit converter
+   * rescales query results, never a formula's.
+   */
+  resultLegendUnit?: string | undefined;
 }): MonitorStepKubernetesMonitor {
   const aggregationType: MetricsAggregationType =
     args.aggregationType || MetricsAggregationType.Sum;
@@ -333,7 +341,7 @@ export function buildKubernetesRatioMonitorConfig(args: {
             title: args.resultLegend,
             description: args.resultLegend,
             legend: args.resultLegend,
-            legendUnit: "%",
+            legendUnit: args.resultLegendUnit ?? "%",
           },
           metricFormulaData: {
             metricFormula:
@@ -700,41 +708,69 @@ const deploymentReplicaMismatchTemplate: KubernetesAlertTemplate = {
   id: "k8s-deployment-replica-mismatch",
   name: "Deployment Replica Mismatch",
   description:
-    "Alert when available replicas are less than desired replicas for a deployment.",
+    "Alert when a deployment has fewer available replicas than desired for fifteen minutes. Computed per deployment as k8s.deployment.desired - k8s.deployment.available, the two replica counts the agent's k8s_cluster receiver reports — it has no unavailable-replicas series.",
   category: "Workload",
   severity: "Warning",
   getMonitorStep: (args: KubernetesAlertTemplateArgs): MonitorStep => {
-    const metricAlias: string = "unavailable_replicas";
+    const metricAlias: string = "replica_shortfall";
 
     return buildKubernetesMonitorStep({
-      kubernetesMonitor: buildKubernetesMonitorConfig({
+      /*
+       * A formula, because there is nothing to read directly. The
+       * k8s_cluster receiver the agent chart runs (collector 0.96.0, no
+       * metric renaming anywhere in the chart) reports a Deployment as
+       * `k8s.deployment.desired` (spec.replicas) and
+       * `k8s.deployment.available` (status.availableReplicas) — there is no
+       * `k8s.deployment.unavailable_replicas`, which is what this template
+       * used to query, so it could never fire.
+       *
+       * `desired - available` is also the better signal than the status
+       * field's unavailableReplicas: that one counts surge pods, so a
+       * healthy rollout whose old pods are all still serving reads as
+       * "unavailable"; this reads 0 (or below — surge makes available
+       * exceed desired) until the deployment is actually short of capacity.
+       */
+      kubernetesMonitor: buildKubernetesRatioMonitorConfig({
         clusterIdentifier: args.clusterIdentifier,
-        metricName: "k8s.deployment.unavailable_replicas",
-        metricAlias,
+        numeratorMetricName: "k8s.deployment.desired",
+        denominatorMetricName: "k8s.deployment.available",
+        /*
+         * 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 both keys on both metrics itself (not
+         * via best-effort enrichment), which is what the formula's
+         * fingerprint join needs.
+         */
+        groupByAttributeKeys: [
+          "resource.k8s.namespace.name",
+          "resource.k8s.deployment.name",
+        ],
+        numeratorAlias: "desired_replicas",
+        denominatorAlias: "available_replicas",
+        resultAlias: metricAlias,
+        resultLegend: "Deployment Replica Shortfall",
+        formula: "desired_replicas - available_replicas",
+        // A pod count, not a percentage.
+        resultLegendUnit: "",
         resourceScope: KubernetesResourceScope.Workload,
         /*
          * 15 minutes, not 5. With the sustained (AllValues) default, the
          * window IS the "how long has this been stuck" knob: every
-         * per-minute bucket in it must report unavailable replicas. A
-         * normal rolling update makes unavailable_replicas non-zero for
-         * the duration of the rollout, and a ten-replica deployment with
+         * per-minute bucket in it must report a shortfall. A rollout whose
+         * new pods are slow to pass readiness keeps available below desired
+         * for its duration, and a ten-replica deployment with
          * maxUnavailable 25% and real readiness probes routinely takes
-         * longer than five minutes — so a five-minute window still paged
+         * longer than five minutes — so a five-minute window would page
          * once per deploy for a condition that is the deploy working.
          */
         rollingTime: RollingTime.Past15Minutes,
-        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).
+         * ONE series per deployment on both sides, from the same
+         * k8s_cluster scrape, so Avg is the per-minute count whatever the
+         * scrape rate. Sum would multiply the shortfall by the number of
+         * scrapes in the minute.
          */
-        groupByAttributeKeys: [
-          "resource.k8s.namespace.name",
-          "resource.k8s.deployment.name",
-        ],
+        aggregationType: MetricsAggregationType.Avg,
       }),
       offlineCriteriaInstance: buildOfflineCriteriaInstance({
         offlineMonitorStatusId: args.offlineMonitorStatusId,
@@ -745,15 +781,19 @@ const deploymentReplicaMismatchTemplate: KubernetesAlertTemplate = {
         filterType: FilterType.GreaterThan,
         value: 0,
         incidentTitle: `[K8s] Deployment Replica Mismatch - ${args.monitorName}`,
-        incidentDescription: `A Kubernetes deployment has unavailable replicas — the desired replica count does not match the available count. This may indicate a failed rollout, image pull errors, insufficient resources, or pod crash loops. The affected namespace and deployment are named under "Affected resource" below, with the rollout-status command under "Start here".`,
-        criteriaName: "Replica Mismatch - Unavailable > 0 for 15 minutes",
+        incidentDescription: `A Kubernetes deployment has had fewer available replicas than it desires for fifteen minutes. This may indicate a failed rollout, image pull errors, insufficient resources, or pod crash loops. The affected namespace and deployment are named under "Affected resource" below, with the rollout-status command under "Start here".`,
+        criteriaName: "Replica Mismatch - Desired > Available for 15 minutes",
         criteriaDescription:
-          "Triggers when a deployment reports unavailable replicas in every sample of a fifteen-minute window — long enough that a normal rolling update has completed and the rollout is genuinely stuck.",
+          "Triggers when a deployment's desired replica count exceeds its available replica count in every sample of a fifteen-minute window — long enough that a normal rolling update has completed and the rollout is genuinely stuck.",
       }),
       onlineCriteriaInstance: buildOnlineCriteriaInstance({
         onlineMonitorStatusId: args.onlineMonitorStatusId,
         metricAlias,
-        filterType: FilterType.EqualTo,
+        /*
+         * `<= 0`, not `= 0`: a surge rollout makes available exceed
+         * desired, and a negative shortfall is healthy too.
+         */
+        filterType: FilterType.LessThanOrEqualTo,
         value: 0,
       }),
     });

package/Types/Monitor/KubernetesMetricCatalog.ts

@@ -6,7 +6,8 @@ export type KubernetesMetricCategory =
   | "Node"
   | "Container"
   | "Workload"
-  | "HPA";
+  | "HPA"
+  | "ControlPlane";
 
 export interface KubernetesMetricDefinition {
   id: string;
@@ -63,6 +64,28 @@ const kubernetesMetricCatalog: Array<KubernetesMetricDefinition> = [
     defaultResourceScope: KubernetesResourceScope.Pod,
     unit: "bytes",
   },
+  {
+    id: "pod-memory-limit-utilization",
+    friendlyName: "Pod Memory Limit Utilization",
+    description:
+      "The pod's memory usage divided by its memory limit, as a ratio (0 to 1) - 0.93 means 93% of the limit, and it is shown as a percentage. kubeletstats divides by the SUM of the pod's container limits, so a pod with a sidecar is measured against its whole budget, and emits nothing for a pod where any container has no memory limit. The kubelet's memory figure includes reclaimable page cache, so a value near 1 means approaching the limit, not necessarily about to be OOMKilled.",
+    metricName: "k8s.pod.memory_limit_utilization",
+    category: "Pod",
+    defaultAggregation: MetricsAggregationType.Max,
+    defaultResourceScope: KubernetesResourceScope.Pod,
+    unit: "ratio",
+  },
+  {
+    id: "pod-cpu-limit-utilization",
+    friendlyName: "Pod CPU Limit Utilization",
+    description:
+      "The pod's CPU usage divided by its CPU limit, as a ratio (0 to 1) - 0.93 means 93% of the limit, and it is shown as a percentage. kubeletstats divides by the SUM of the pod's container limits and emits nothing for a pod where any container has no CPU limit. Near 1 the kernel's CFS quota is throttling the pod: it gets slower rather than failing.",
+    metricName: "k8s.pod.cpu_limit_utilization",
+    category: "Pod",
+    defaultAggregation: MetricsAggregationType.Max,
+    defaultResourceScope: KubernetesResourceScope.Pod,
+    unit: "ratio",
+  },
   {
     id: "pod-network-io",
     friendlyName: "Pod Network I/O (Cumulative, Both Directions)",
@@ -87,6 +110,17 @@ const kubernetesMetricCatalog: Array<KubernetesMetricDefinition> = [
     defaultResourceScope: KubernetesResourceScope.Node,
     unit: "cores",
   },
+  {
+    id: "node-allocatable-cpu",
+    friendlyName: "Node Allocatable CPU",
+    description:
+      "CPU cores on the node that pods can be scheduled against: the node's capacity minus what the kubelet reserves for the operating system and Kubernetes daemons (system-reserved, kube-reserved). Reported by the k8s_cluster receiver. The scheduler never places pods whose CPU requests add up past it, so it is the right denominator for a node CPU percentage - usage or summed container requests divided by this.",
+    metricName: "k8s.node.allocatable_cpu",
+    category: "Node",
+    defaultAggregation: MetricsAggregationType.Avg,
+    defaultResourceScope: KubernetesResourceScope.Node,
+    unit: "cores",
+  },
   {
     id: "node-memory-usage",
     friendlyName: "Node Memory Usage",
@@ -107,6 +141,17 @@ const kubernetesMetricCatalog: Array<KubernetesMetricDefinition> = [
     defaultResourceScope: KubernetesResourceScope.Node,
     unit: "bytes",
   },
+  {
+    id: "node-allocatable-memory",
+    friendlyName: "Node Allocatable Memory",
+    description:
+      "Memory in bytes on the node that pods can use: the node's capacity minus what the kubelet reserves for the operating system and Kubernetes daemons (system-reserved, kube-reserved) and the hard eviction threshold. Reported by the k8s_cluster receiver. The scheduler never places pods whose memory requests add up past it, so it - not the node's physical RAM - is the denominator for a meaningful node memory percentage.",
+    metricName: "k8s.node.allocatable_memory",
+    category: "Node",
+    defaultAggregation: MetricsAggregationType.Avg,
+    defaultResourceScope: KubernetesResourceScope.Node,
+    unit: "bytes",
+  },
   {
     id: "node-condition-ready",
     friendlyName: "Node Ready Condition",
@@ -192,12 +237,22 @@ const kubernetesMetricCatalog: Array<KubernetesMetricDefinition> = [
     unit: "count",
   },
 
-  // Workload Metrics
+  /*
+   * Workload Metrics
+   *
+   * These are the k8s_cluster receiver's names, which the agent chart
+   * forwards unrenamed: `k8s.deployment.available` / `.desired`, not the
+   * `*_replicas` spelling the Deployment status fields use. The receiver
+   * has no "unavailable" series at all — a replica shortfall is
+   * `desired - available` (see the k8s-deployment-replica-mismatch
+   * template).
+   */
   {
     id: "deployment-available-replicas",
     friendlyName: "Deployment Available Replicas",
-    description: "Number of available replicas in a deployment",
-    metricName: "k8s.deployment.available_replicas",
+    description:
+      "Number of pods targeted by the deployment that have been ready for at least minReadySeconds",
+    metricName: "k8s.deployment.available",
     category: "Workload",
     defaultAggregation: MetricsAggregationType.Min,
     defaultResourceScope: KubernetesResourceScope.Workload,
@@ -206,18 +261,8 @@ const kubernetesMetricCatalog: Array<KubernetesMetricDefinition> = [
   {
     id: "deployment-desired-replicas",
     friendlyName: "Deployment Desired Replicas",
-    description: "Number of desired replicas in a deployment",
-    metricName: "k8s.deployment.desired_replicas",
-    category: "Workload",
-    defaultAggregation: MetricsAggregationType.Max,
-    defaultResourceScope: KubernetesResourceScope.Workload,
-    unit: "count",
-  },
-  {
-    id: "deployment-unavailable-replicas",
-    friendlyName: "Deployment Unavailable Replicas",
-    description: "Number of unavailable replicas in a deployment",
-    metricName: "k8s.deployment.unavailable_replicas",
+    description: "Number of desired replicas (spec.replicas) in a deployment",
+    metricName: "k8s.deployment.desired",
     category: "Workload",
     defaultAggregation: MetricsAggregationType.Max,
     defaultResourceScope: KubernetesResourceScope.Workload,
@@ -247,8 +292,8 @@ const kubernetesMetricCatalog: Array<KubernetesMetricDefinition> = [
   {
     id: "statefulset-ready-replicas",
     friendlyName: "StatefulSet Ready Replicas",
-    description: "Number of ready replicas in a StatefulSet",
-    metricName: "k8s.statefulset.ready_replicas",
+    description: "Number of pods created by a StatefulSet that are Ready",
+    metricName: "k8s.statefulset.ready_pods",
     category: "Workload",
     defaultAggregation: MetricsAggregationType.Min,
     defaultResourceScope: KubernetesResourceScope.Workload,
@@ -316,6 +361,49 @@ const kubernetesMetricCatalog: Array<KubernetesMetricDefinition> = [
     defaultResourceScope: KubernetesResourceScope.Workload,
     unit: "count",
   },
+
+  /*
+   * Control Plane Metrics
+   *
+   * Prometheus metrics the agent scrapes from etcd, the API server and the
+   * scheduler, and only when its control-plane scrape is enabled
+   * (controlPlane.enabled). Managed clusters (EKS / GKE / AKS) do not
+   * expose these endpoints, so on those these metrics never report.
+   * Each is one cluster-wide signal, hence the Cluster scope.
+   */
+  {
+    id: "etcd-has-leader",
+    friendlyName: "etcd Has Leader",
+    description:
+      "Whether the etcd member sees an elected leader (1 = has a leader, 0 = no leader). A flag, not a count: without a leader etcd cannot commit writes, so the API server cannot persist any change. Min over the window catches a single leaderless sample.",
+    metricName: "etcd_server_has_leader",
+    category: "ControlPlane",
+    defaultAggregation: MetricsAggregationType.Min,
+    defaultResourceScope: KubernetesResourceScope.Cluster,
+    unit: "",
+  },
+  {
+    id: "apiserver-inflight-requests",
+    friendlyName: "API Server In-Flight Requests",
+    description:
+      "Requests the Kubernetes API server is processing right now, one series per request_kind (mutating / readOnly). The server admits a bounded number at once (--max-requests-inflight, default 400; --max-mutating-requests-inflight, default 200) and rejects the rest with HTTP 429, so a value held at its limit means clients are being throttled.",
+    metricName: "apiserver_current_inflight_requests",
+    category: "ControlPlane",
+    defaultAggregation: MetricsAggregationType.Max,
+    defaultResourceScope: KubernetesResourceScope.Cluster,
+    unit: "count",
+  },
+  {
+    id: "scheduler-pending-pods",
+    friendlyName: "Scheduler Pending Pods",
+    description:
+      "Pods waiting in the kube-scheduler's queues, one series per queue (active, backoff, unschedulable, and gated on newer versions). A count that stays above zero means pods the scheduler cannot place - usually not enough allocatable CPU or memory, or taints, affinity or volume constraints no node satisfies.",
+    metricName: "scheduler_pending_pods",
+    category: "ControlPlane",
+    defaultAggregation: MetricsAggregationType.Max,
+    defaultResourceScope: KubernetesResourceScope.Cluster,
+    unit: "count",
+  },
 ];
 
 export function getAllKubernetesMetrics(): Array<KubernetesMetricDefinition> {
@@ -347,5 +435,16 @@ export function getKubernetesMetricByMetricName(
 }
 
 export function getAllKubernetesMetricCategories(): Array<KubernetesMetricCategory> {
-  return ["Pod", "Node", "Container", "Workload", "HPA"];
+  return ["Pod", "Node", "Container", "Workload", "HPA", "ControlPlane"];
+}
+
+/**
+ * How a category is titled in a picker. The category values are
+ * identifiers ("ControlPlane" matches the alert templates' category), not
+ * prose.
+ */
+export function getKubernetesMetricCategoryLabel(
+  category: KubernetesMetricCategory,
+): string {
+  return category === "ControlPlane" ? "Control Plane" : category;
 }

package/Types/Monitor/MetricMonitor/MetricCriteriaContext.ts

@@ -78,6 +78,13 @@ export interface MetricAnomalyBaseline {
 export default interface MetricCriteriaContext {
   metricName: string;
   alias: string;
+  /**
+   * The legend the user gave the query or formula the criteria targets
+   * ("Node Memory Utilization (%)"), when it is more than the bare alias.
+   * `metricName` is the formula EXPRESSION for a formula criteria, which is
+   * not something to title a list with.
+   */
+  displayName?: string | undefined;
   unit: string | null;
   aggregationType: MetricsAggregationType | null;
   isFormula: boolean;
@@ -114,6 +121,13 @@ export default interface MetricCriteriaContext {
    * breached" without re-querying.
    */
   totalSamplesInWindow?: number | undefined;
+  /**
+   * The smallest and largest sample in the evaluation window, in the same
+   * display unit as `breachingSamples`. Lets a reader of the context name
+   * the series' worst value even when the criteria compared an aggregate
+   * (a Sum over the window can breach while no single sample does).
+   */
+  sampleValueRange?: { min: number; max: number } | undefined;
   /**
    * For formulas: metadata for each variable the formula references,
    * in the order they appear in the expression. Consumers use this to

package/Types/Monitor/MetricMonitor/MetricMonitorResponse.ts

@@ -6,6 +6,37 @@ import ObjectID from "../../ObjectID";
 import Dictionary from "../../Dictionary";
 import MetricSeriesResult from "./MetricSeriesResult";
 
+/**
+ * Where a platform resource breakdown came from.
+ *
+ * The worker scans raw datapoints once PER QUERY to name the resources
+ * behind a breach. A monitor step can have several queries — every ratio
+ * template has two (used ÷ allocatable, used ÷ total) and a formula over
+ * them — and the breakdown used to be a single field that each query's
+ * scan overwrote, so the LAST query won. For "High Node Memory
+ * Utilization" that is the denominator, k8s.node.allocatable_memory: the
+ * email listed every node's allocatable bytes under a "> 85%" criteria.
+ *
+ * Tagging each scan with its query lets the evaluator use the one scan
+ * that measured what the matched criteria actually compared, and refuse
+ * to borrow a sibling query's numbers when the criteria targets a formula.
+ */
+export interface PlatformResourceBreakdownSource {
+  /**
+   * `metricAliasData.metricVariable` of the query this scan was taken for
+   * (e.g. "used_mem"). Absent on breakdowns built before it existed.
+   */
+  metricAlias?: string | undefined;
+  /**
+   * The unit the scanned values are in: the platform catalog's unit when
+   * the catalog knows the metric, otherwise the unit the OpenTelemetry
+   * exporter declared for it (MetricType.unit, e.g. "By"). The raw scan
+   * never goes through MetricResultUnitConverter, so this is the metric's
+   * NATIVE unit, never a legendUnit. Absent when neither is known.
+   */
+  metricUnit?: string | undefined;
+}
+
 export interface KubernetesAffectedResource {
   podName?: string | undefined;
   namespace?: string | undefined;
@@ -25,7 +56,8 @@ export interface KubernetesAffectedResource {
   lowestMetricValue?: number | undefined;
 }
 
-export interface KubernetesResourceBreakdown {
+export interface KubernetesResourceBreakdown
+  extends PlatformResourceBreakdownSource {
   clusterName: string;
   metricName: string;
   metricFriendlyName: string;
@@ -45,9 +77,16 @@ export interface ProxmoxAffectedResource {
   /** `node` label — present only on the pve_*_info metadata series. */
   nodeName?: string | undefined;
   metricValue: number;
+  /**
+   * Lowest sample seen for this resource in the monitoring window — what a
+   * criteria that fires when the metric FALLS breached on. See
+   * KubernetesAffectedResource.lowestMetricValue.
+   */
+  lowestMetricValue?: number | undefined;
 }
 
-export interface ProxmoxResourceBreakdown {
+export interface ProxmoxResourceBreakdown
+  extends PlatformResourceBreakdownSource {
   clusterName: string;
   metricName: string;
   metricFriendlyName: string;
@@ -79,9 +118,16 @@ export interface VMwareAffectedResource {
   /** `resource.vcenter.resource_pool.inventory_path` — the pool's unique path. */
   resourcePoolPath?: string | undefined;
   metricValue: number;
+  /**
+   * Lowest sample seen for this resource in the monitoring window — what a
+   * criteria that fires when the metric FALLS breached on. See
+   * KubernetesAffectedResource.lowestMetricValue.
+   */
+  lowestMetricValue?: number | undefined;
 }
 
-export interface VMwareResourceBreakdown {
+export interface VMwareResourceBreakdown
+  extends PlatformResourceBreakdownSource {
   /** The `vmware.vcenter.name` the agent stamps — one per vCenter. */
   vcenterName: string;
   metricName: string;
@@ -100,9 +146,15 @@ export interface CephAffectedResource {
   /** `hostname` label — present only on the *_metadata series. */
   hostname?: string | undefined;
   metricValue: number;
+  /**
+   * Lowest sample seen for this resource in the monitoring window — what a
+   * criteria that fires when the metric FALLS breached on. See
+   * KubernetesAffectedResource.lowestMetricValue.
+   */
+  lowestMetricValue?: number | undefined;
 }
 
-export interface CephResourceBreakdown {
+export interface CephResourceBreakdown extends PlatformResourceBreakdownSource {
   clusterName: string;
   metricName: string;
   metricFriendlyName: string;
@@ -120,9 +172,16 @@ export interface DockerSwarmAffectedResource {
   /** `docker.swarm.service.name` datapoint label, when the agent stamps it. */
   serviceName?: string | undefined;
   metricValue: number;
+  /**
+   * Lowest sample seen for this resource in the monitoring window — what a
+   * criteria that fires when the metric FALLS breached on. See
+   * KubernetesAffectedResource.lowestMetricValue.
+   */
+  lowestMetricValue?: number | undefined;
 }
 
-export interface DockerSwarmResourceBreakdown {
+export interface DockerSwarmResourceBreakdown
+  extends PlatformResourceBreakdownSource {
   clusterName: string;
   metricName: string;
   metricFriendlyName: string;
@@ -142,6 +201,22 @@ export default interface MetricMonitorResponse {
   vmwareResourceBreakdown?: VMwareResourceBreakdown | undefined;
   cephResourceBreakdown?: CephResourceBreakdown | undefined;
   dockerSwarmResourceBreakdown?: DockerSwarmResourceBreakdown | undefined;
+  /*
+   * One breakdown per query whose raw scan returned rows, in query order,
+   * each tagged with the query it was scanned for. These supersede the
+   * singular fields above, which the worker no longer writes: a single
+   * field could only ever hold one query's scan, and holding the last one
+   * put the denominator of every ratio template into the email. The
+   * evaluator still reads the singular field when the plural one is
+   * absent, so a payload built before this change renders as it did.
+   */
+  kubernetesResourceBreakdowns?: Array<KubernetesResourceBreakdown> | undefined;
+  proxmoxResourceBreakdowns?: Array<ProxmoxResourceBreakdown> | undefined;
+  vmwareResourceBreakdowns?: Array<VMwareResourceBreakdown> | undefined;
+  cephResourceBreakdowns?: Array<CephResourceBreakdown> | undefined;
+  dockerSwarmResourceBreakdowns?:
+    | Array<DockerSwarmResourceBreakdown>
+    | undefined;
   /**
    * Per-series breakdown when any queryConfig sets groupByAttributeKeys.
    * Each entry carries a fingerprint, the label values identifying that
@@ -152,11 +227,19 @@ export default interface MetricMonitorResponse {
    */
   seriesBreakdown?: Array<MetricSeriesResult> | undefined;
   /**
-   * Native units (UCUM / OTel) per referenced metric name, lowercased.
-   * Loaded once when the monitor data is fetched. The criteria
-   * evaluator falls back to this when the query alias has no explicit
-   * `legendUnit` so threshold unit conversion (e.g. % vs the
-   * dimensionless "1" used by ratio metrics) still works.
+   * The unit each referenced metric's stored values are in, keyed by
+   * lowercased metric name. Loaded once when the monitor data is fetched.
+   * The criteria evaluator falls back to this when the query alias has no
+   * explicit `legendUnit`, so threshold unit conversion (e.g. % vs the
+   * dimensionless "1" used by ratio metrics) still works and the numbers
+   * in the notification carry a unit.
+   *
+   * For a generic Metrics monitor this is the OpenTelemetry-declared unit
+   * (MetricType.unit). For a platform monitor (Kubernetes, Docker, Host,
+   * Proxmox, ...) the platform's metric catalog wins over it — see
+   * PlatformMetricUnitUtil — because some receivers declare a unit that
+   * does not describe the values they send (docker_stats reports
+   * container.cpu.utilization as 0–100 under the unit "1").
    */
   nativeUnitsByMetricName?: Dictionary<string> | undefined;
 }