@oneuptime/common 13.0.0 → 13.0.1

package/Tests/Server/Utils/Monitor/MonitorCriteriaEvaluator.test.ts

@@ -3,6 +3,7 @@ import Monitor from "../../../../Models/DatabaseModels/Monitor";
 import MonitorStep from "../../../../Types/Monitor/MonitorStep";
 import MetricMonitorResponse, {
   ProxmoxAffectedResource,
+  VMwareAffectedResource,
   CephAffectedResource,
   KubernetesAffectedResource,
 } from "../../../../Types/Monitor/MetricMonitor/MetricMonitorResponse";
@@ -14,6 +15,10 @@ import {
   getCephAlertTemplateById,
   CephAlertTemplate,
 } from "../../../../Types/Monitor/CephAlertTemplates";
+import {
+  getVMwareAlertTemplateById,
+  VMwareAlertTemplate,
+} from "../../../../Types/Monitor/VMwareAlertTemplates";
 import ObjectID from "../../../../Types/ObjectID";
 import MonitorCriteriaInstance from "../../../../Types/Monitor/MonitorCriteriaInstance";
 import {
@@ -52,6 +57,11 @@ type EvaluatorPrivate = {
     monitorStep: MonitorStep;
     monitor: Monitor;
   }) => string | null;
+  buildVMwareRootCauseContext: (input: {
+    dataToProcess: unknown;
+    monitorStep: MonitorStep;
+    monitor: Monitor;
+  }) => string | null;
   buildCephRootCauseContext: (input: {
     dataToProcess: unknown;
     monitorStep: MonitorStep;
@@ -93,6 +103,23 @@ function proxmoxStep(): MonitorStep {
   return template.getMonitorStep(templateArgs());
 }
 
+function vmwareStep(): MonitorStep {
+  const template: VMwareAlertTemplate | undefined = getVMwareAlertTemplateById(
+    "vmware-host-cpu-saturation",
+  );
+  if (!template) {
+    throw new Error("vmware-host-cpu-saturation template missing");
+  }
+  return template.getMonitorStep({
+    vcenterIdentifier: "vcsa-prod",
+    onlineMonitorStatusId: ObjectID.generate(),
+    offlineMonitorStatusId: ObjectID.generate(),
+    defaultIncidentSeverityId: ObjectID.generate(),
+    defaultAlertSeverityId: ObjectID.generate(),
+    monitorName: "Test Monitor",
+  });
+}
+
 function cephStep(): MonitorStep {
   const template: CephAlertTemplate | undefined =
     getCephAlertTemplateById("ceph-osd-down");
@@ -315,6 +342,341 @@ describe("MonitorCriteriaEvaluator - Proxmox root cause breakdown", () => {
   });
 });
 
+describe("MonitorCriteriaEvaluator - VMware root cause breakdown", () => {
+  /*
+   * VMware twin of the Proxmox block. The differences are deliberate:
+   * identity comes from the vcenter receiver's RESOURCE attributes
+   * (stored `resource.vcenter.*`), the table is
+   * Resource / Kind / Host / Cluster / Value, and utilization metrics
+   * are already 0–100 percentages (catalog unit "%") — never [0, 1]
+   * ratios — so the Value column must print them as-is and never ×100.
+   */
+  test("renders the Resource/Kind/Host/Cluster/Value table: zero rows dropped, worst first, % as-is", () => {
+    const affectedResources: Array<VMwareAffectedResource> = [
+      {
+        datacenterName: "DC1",
+        clusterName: "prod-cluster",
+        hostName: "esx-01",
+        metricValue: 42.5,
+      },
+      {
+        datacenterName: "DC1",
+        clusterName: "prod-cluster",
+        hostName: "esx-02",
+        metricValue: 97.25,
+      },
+      // Zero-value row — must be dropped from the table.
+      {
+        datacenterName: "DC1",
+        clusterName: "prod-cluster",
+        hostName: "esx-03",
+        metricValue: 0,
+      },
+    ];
+
+    const context: string | null = Evaluator.buildVMwareRootCauseContext({
+      dataToProcess: metricResponse({
+        vmwareResourceBreakdown: {
+          vcenterName: "vcsa-prod",
+          metricName: "vcenter.host.cpu.utilization",
+          metricFriendlyName: "Host CPU Utilization",
+          affectedResources,
+          attributes: {},
+        },
+      }),
+      monitorStep: vmwareStep(),
+      monitor: new Monitor(),
+    });
+
+    expect(context).not.toBeNull();
+    expect(context).toContain("**vCenter Details**");
+    expect(context).toContain("- vCenter: vcsa-prod");
+    expect(context).toContain(
+      "- Metric: Host CPU Utilization (`vcenter.host.cpu.utilization`)",
+    );
+
+    expect(context).toContain("| Resource | Kind | Host | Cluster | Value |");
+    // Worst (97.25) sorts above 42.5; the zero row is gone entirely.
+    const worstIndex: number = context!.indexOf("`esx-02`");
+    const mildIndex: number = context!.indexOf("`esx-01`");
+    expect(worstIndex).toBeGreaterThan(-1);
+    expect(mildIndex).toBeGreaterThan(worstIndex);
+    expect(context).not.toContain("esx-03");
+    expect(context).toContain("**Affected Resources** (2 total)");
+
+    /*
+     * The catalog declares "%" for the receiver's utilization metrics,
+     * whose values are already percentages: 97.25 must read "97.25%",
+     * never "9725.00%". A host IS the resource, so its Host column is
+     * "-" and the Cluster column carries the cluster it belongs to.
+     */
+    expect(context).toContain(
+      "| `esx-02` | Host | - | `prod-cluster` | **97.25%** |",
+    );
+    expect(context).toContain(
+      "| `esx-01` | Host | - | `prod-cluster` | **42.50%** |",
+    );
+    expect(context).not.toContain("9725");
+  });
+
+  test("a sub-1 percentage value is not mistaken for a ratio", () => {
+    /*
+     * 0.42 on a "%" metric is 0.42% of a host's CPU. Proxmox's
+     * `_ratio` metrics would render that as 42.00%; the vcenter
+     * receiver never emits ratios, so the same number must stay 0.42%.
+     */
+    const context: string | null = Evaluator.buildVMwareRootCauseContext({
+      dataToProcess: metricResponse({
+        vmwareResourceBreakdown: {
+          vcenterName: "vcsa-prod",
+          metricName: "vcenter.host.cpu.utilization",
+          metricFriendlyName: "Host CPU Utilization",
+          affectedResources: [
+            { datacenterName: "DC1", hostName: "esx-01", metricValue: 0.42 },
+          ],
+          attributes: {},
+        },
+      }),
+      monitorStep: vmwareStep(),
+      monitor: new Monitor(),
+    });
+
+    expect(context).toContain("| `esx-01` | Host | - | - | **0.42%** |");
+    expect(context).not.toContain("42.00%");
+  });
+
+  test("renders VM rows with their parent host and cluster, and bytes at human scale", () => {
+    const context: string | null = Evaluator.buildVMwareRootCauseContext({
+      dataToProcess: metricResponse({
+        vmwareResourceBreakdown: {
+          vcenterName: "vcsa-prod",
+          metricName: "vcenter.vm.disk.usage",
+          metricFriendlyName: "VM Disk Usage",
+          affectedResources: [
+            {
+              datacenterName: "DC1",
+              clusterName: "prod-cluster",
+              hostName: "esx-02",
+              vmName: "db-01",
+              vmId: "5029abcd-1111-2222-3333-444455556666",
+              resourcePoolName: "Resources",
+              resourcePoolPath: "/DC1/host/prod-cluster/Resources",
+              metricValue: 8589934592,
+            },
+            {
+              datacenterName: "DC1",
+              hostName: "esx-standalone",
+              vmName: "lab-01",
+              vmId: "5029abcd-aaaa-bbbb-cccc-ddddeeeeffff",
+              metricValue: 1073741824,
+            },
+          ],
+          attributes: {},
+        },
+      }),
+      monitorStep: vmwareStep(),
+      monitor: new Monitor(),
+    });
+
+    /*
+     * A VM row carries a resource pool AND a host, but it is still a
+     * VM: the Kind column must say so (VM check runs first), the Host
+     * column is the ESXi host running it, and the on-call engineer
+     * should not have to divide by 2^30 in their head.
+     */
+    expect(context).toContain(
+      "| `db-01` | Virtual Machine | `esx-02` | `prod-cluster` | **8.59 GB** |",
+    );
+    // A VM on a standalone ESXi host has no cluster.
+    expect(context).toContain(
+      "| `lab-01` | Virtual Machine | `esx-standalone` | - | **1.07 GB** |",
+    );
+    expect(context).not.toContain("**8589934592**");
+    expect(context).not.toContain("Resource Pool");
+  });
+
+  test("renders datastore, cluster, datacenter and resource pool rows by their own identity", () => {
+    const context: string | null = Evaluator.buildVMwareRootCauseContext({
+      dataToProcess: metricResponse({
+        vmwareResourceBreakdown: {
+          vcenterName: "vcsa-prod",
+          metricName: "vcenter.datacenter.host.count",
+          metricFriendlyName: "Datacenter Host Count",
+          affectedResources: [
+            { datacenterName: "DC1", metricValue: 4 },
+            {
+              datacenterName: "DC1",
+              clusterName: "prod-cluster",
+              metricValue: 3,
+            },
+            {
+              datacenterName: "DC1",
+              datastoreName: "vsan-ds-01",
+              metricValue: 2,
+            },
+            {
+              datacenterName: "DC1",
+              clusterName: "prod-cluster",
+              resourcePoolName: "batch",
+              resourcePoolPath: "/DC1/host/prod-cluster/Resources/batch",
+              metricValue: 1,
+            },
+          ],
+          attributes: {},
+        },
+      }),
+      monitorStep: vmwareStep(),
+      monitor: new Monitor(),
+    });
+
+    /*
+     * `{hosts}` is an annotation-only unit, so counts render as bare
+     * integers. Each kind resolves by the most specific identity
+     * attribute it carries: a datacenter-only row is a Datacenter, a
+     * cluster row shows no duplicate Cluster cell, a pool shows its
+     * name with the inventory path (pool names are only unique within
+     * a parent).
+     */
+    expect(context).toContain("| `DC1` | Datacenter | - | - | **4** |");
+    expect(context).toContain("| `prod-cluster` | Cluster | - | - | **3** |");
+    expect(context).toContain("| `vsan-ds-01` | Datastore | - | - | **2** |");
+    expect(context).toContain(
+      "| `batch` (`/DC1/host/prod-cluster/Resources/batch`) | Resource Pool | - | `prod-cluster` | **1** |",
+    );
+  });
+
+  test("renders latency in the catalog's unit", () => {
+    const context: string | null = Evaluator.buildVMwareRootCauseContext({
+      dataToProcess: metricResponse({
+        vmwareResourceBreakdown: {
+          vcenterName: "vcsa-prod",
+          metricName: "vcenter.host.disk.latency.max",
+          metricFriendlyName: "Host Disk Latency (Max)",
+          affectedResources: [
+            { datacenterName: "DC1", hostName: "esx-01", metricValue: 85 },
+          ],
+          attributes: {},
+        },
+      }),
+      monitorStep: vmwareStep(),
+      monitor: new Monitor(),
+    });
+
+    // Unit from the catalog ("ms"), not a bare, unit-less 85.
+    expect(context).toMatch(
+      /\| `esx-01` \| Host \| - \| - \| \*\*85(\.00)? ms\*\* \|/,
+    );
+  });
+
+  test("caps the table at 10 rows, worst first, with an overflow suffix", () => {
+    const affectedResources: Array<VMwareAffectedResource> = [];
+    for (let i: number = 1; i <= 12; i++) {
+      affectedResources.push({
+        datacenterName: "DC1",
+        hostName: `esx-${String(i).padStart(2, "0")}`,
+        metricValue: i,
+      });
+    }
+
+    const context: string | null = Evaluator.buildVMwareRootCauseContext({
+      dataToProcess: metricResponse({
+        vmwareResourceBreakdown: {
+          vcenterName: "vcsa-prod",
+          metricName: "vcenter.host.network.packet.error.rate",
+          metricFriendlyName: "Host Network Packet Error Rate",
+          affectedResources,
+          attributes: {},
+        },
+      }),
+      monitorStep: vmwareStep(),
+      monitor: new Monitor(),
+    });
+
+    expect(context).toContain("**Affected Resources** (12 total)");
+    expect(context).toContain("*... and 2 more affected resources*");
+    // The worst rows survive the cap; the mildest two are cut.
+    expect(context).toContain("`esx-12`");
+    expect(context).toContain("`esx-03`");
+    expect(context).not.toContain("`esx-02`");
+    expect(context).not.toContain("`esx-01`");
+  });
+
+  test("identity-less breakdowns render no table and fall back to the metric summary", () => {
+    const context: string | null = Evaluator.buildVMwareRootCauseContext({
+      dataToProcess: metricResponse({
+        vmwareResourceBreakdown: {
+          vcenterName: "vcsa-prod",
+          metricName: "vcenter.datacenter.vm.count",
+          metricFriendlyName: "Datacenter VM Count",
+          affectedResources: [
+            // A value but NO identity attributes.
+            { metricValue: 3 },
+          ],
+          attributes: {},
+        },
+        metricResult: [{ data: [{}, {}] } as any],
+      }),
+      monitorStep: vmwareStep(),
+      monitor: new Monitor(),
+    });
+
+    expect(context).not.toContain(
+      "| Resource | Kind | Host | Cluster | Value |",
+    );
+    expect(context).toContain("**Metric Summary**");
+    expect(context).toContain("- 2 metric data point(s) returned");
+  });
+
+  test("surfaces the worker's resource-filter mapping (resource.vcenter.*) in the vCenter context", () => {
+    const step: MonitorStep = vmwareStep();
+    /*
+     * The worker maps resourceFilters to `resource.vcenter.*` equality
+     * attributes; the evaluator surfaces the same filters so the
+     * incident shows WHAT was scoped.
+     */
+    step.data!.vmwareMonitor!.resourceFilters = {
+      datacenterName: "DC1",
+      clusterName: "prod-cluster",
+      hostName: "esx-01",
+      vmName: "db-01",
+      datastoreName: "vsan-ds-01",
+      resourcePoolPath: "/DC1/host/prod-cluster/Resources/batch",
+    };
+
+    const context: string | null = Evaluator.buildVMwareRootCauseContext({
+      dataToProcess: metricResponse(),
+      monitorStep: step,
+      monitor: new Monitor(),
+    });
+
+    expect(context).toContain("**vCenter Details**");
+    expect(context).toContain("- vCenter: vcsa-prod");
+    expect(context).toContain("- Datacenter Filter: DC1");
+    expect(context).toContain("- Cluster Filter: prod-cluster");
+    expect(context).toContain("- Host Filter: esx-01");
+    expect(context).toContain("- Virtual Machine Filter: db-01");
+    expect(context).toContain("- Datastore Filter: vsan-ds-01");
+    expect(context).toContain(
+      "- Resource Pool Filter: /DC1/host/prod-cluster/Resources/batch",
+    );
+    // No breakdown attached: the metric name comes from the step's query.
+    expect(context).toContain("- Metric: `vcenter.host.cpu.utilization`");
+    // Nothing Proxmox leaks into a VMware root cause.
+    expect(context).not.toContain("Proxmox");
+    expect(context).not.toContain("Scope Filter");
+  });
+
+  test("returns null when there is neither a step config nor a breakdown", () => {
+    const context: string | null = Evaluator.buildVMwareRootCauseContext({
+      dataToProcess: metricResponse(),
+      monitorStep: new MonitorStep(),
+      monitor: new Monitor(),
+    });
+
+    expect(context).toBeNull();
+  });
+});
+
 describe("MonitorCriteriaEvaluator - Ceph root cause breakdown", () => {
   test("renders the Daemon/Pool/Host/Value table with pool name+id cells", () => {
     const affectedResources: Array<CephAffectedResource> = [

package/Tests/Server/Utils/Monitor/MonitorDependencySuppressionCreatorSkip.test.ts

@@ -220,6 +220,7 @@ describe("Dependency-suppression skip block in the alert / incident creators", (
         kubernetesClusterIds: [],
         serviceIds: [],
         proxmoxClusterIds: [],
+        vmwareVCenterIds: [],
         cephClusterIds: [],
         dockerSwarmClusterIds: [],
         iotFleetIds: [],

package/Tests/Server/Utils/Monitor/MonitorIncidentResourceLinking.test.ts

@@ -22,6 +22,7 @@ import NetworkDeviceOwnerUserService from "../../../../Server/Services/NetworkDe
 import PodmanHostService from "../../../../Server/Services/PodmanHostService";
 import ProxmoxClusterService from "../../../../Server/Services/ProxmoxClusterService";
 import ServiceService from "../../../../Server/Services/ServiceService";
+import VMwareVCenterService from "../../../../Server/Services/VMwareVCenterService";
 import ProjectScopedReferenceValidator from "../../../../Server/Utils/Database/ProjectScopedReferenceValidator";
 import MonitorResourceContextUtil from "../../../../Server/Utils/Monitor/MonitorResourceContext";
 import { SeriesResolvedResourceIds } from "../../../../Server/Utils/Monitor/SeriesResourceLinker";
@@ -127,7 +128,7 @@ function idsOn(
 }
 
 /*
- * The nine-relation shape MonitorResourceContext resolves from the
+ * The ten-relation shape MonitorResourceContext resolves from the
  * monitor's own step config. Tests stub the util and hand back one of
  * these, spreading over it to name only the relations under test.
  */
@@ -139,6 +140,7 @@ function emptyResourceContext(): SeriesResolvedResourceIds {
     kubernetesClusterIds: [],
     serviceIds: [],
     proxmoxClusterIds: [],
+    vmwareVCenterIds: [],
     cephClusterIds: [],
     dockerSwarmClusterIds: [],
     iotFleetIds: [],
@@ -154,6 +156,7 @@ describe("Incidents link the resources their series identifies", () => {
   let dockerHostRows: Array<{ _id: string }> = [];
   let podmanHostRows: Array<{ _id: string }> = [];
   let proxmoxClusterRows: Array<{ _id: string }> = [];
+  let vmwareVCenterRows: Array<{ _id: string }> = [];
   let cephClusterRows: Array<{ _id: string }> = [];
   let dockerSwarmClusterRows: Array<{ _id: string }> = [];
   let iotFleetRows: Array<{ _id: string }> = [];
@@ -169,6 +172,7 @@ describe("Incidents link the resources their series identifies", () => {
     dockerHostRows = [];
     podmanHostRows = [];
     proxmoxClusterRows = [];
+    vmwareVCenterRows = [];
     cephClusterRows = [];
     dockerSwarmClusterRows = [];
     iotFleetRows = [];
@@ -212,6 +216,9 @@ describe("Incidents link the resources their series identifies", () => {
     jest.spyOn(ProxmoxClusterService, "findBy").mockImplementation(async () => {
       return proxmoxClusterRows as never;
     });
+    jest.spyOn(VMwareVCenterService, "findBy").mockImplementation(async () => {
+      return vmwareVCenterRows as never;
+    });
     jest.spyOn(CephClusterService, "findBy").mockImplementation(async () => {
       return cephClusterRows as never;
     });
@@ -355,6 +362,7 @@ describe("Incidents link the resources their series identifies", () => {
     dockerHostRows = [{ _id: "docker-1" }];
     podmanHostRows = [{ _id: "podman-1" }];
     proxmoxClusterRows = [{ _id: "pve-1" }];
+    vmwareVCenterRows = [{ _id: "vcsa-1" }];
     cephClusterRows = [{ _id: "ceph-1" }];
     dockerSwarmClusterRows = [{ _id: "swarm-1" }];
     iotFleetRows = [{ _id: "fleet-1" }];
@@ -374,6 +382,7 @@ describe("Incidents link the resources their series identifies", () => {
             "oneuptime.docker.host.name": "docker-box",
             "oneuptime.podman.host.name": "podman-box",
             "proxmox.cluster.name": "pve",
+            "vmware.vcenter.name": "vcsa",
             "ceph.cluster.name": "ceph",
             "docker.swarm.cluster.name": "swarm",
             "iot.fleet.name": "fleet",
@@ -392,6 +401,7 @@ describe("Incidents link the resources their series identifies", () => {
     expect(idsOn(incident.dockerHosts)).toEqual(["docker-1"]);
     expect(idsOn(incident.podmanHosts)).toEqual(["podman-1"]);
     expect(idsOn(incident.proxmoxClusters)).toEqual(["pve-1"]);
+    expect(idsOn(incident.vmwareVCenters)).toEqual(["vcsa-1"]);
     expect(idsOn(incident.cephClusters)).toEqual(["ceph-1"]);
     expect(idsOn(incident.dockerSwarmClusters)).toEqual(["swarm-1"]);
     expect(idsOn(incident.iotFleets)).toEqual(["fleet-1"]);
@@ -482,6 +492,55 @@ describe("Incidents link the resources their series identifies", () => {
     ]);
   });
 
+  it("merges the monitor's step-config vCenter with the one the series names", async () => {
+    vmwareVCenterRows = [{ _id: "vcsa-from-label" }];
+    resourceContext = {
+      ...emptyResourceContext(),
+      vmwareVCenterIds: ["vcsa-from-step-config"],
+    };
+
+    await MonitorIncident.criteriaMetCreateIncidentsAndUpdateMonitorStatus({
+      criteriaInstance: criteriaInstance(),
+      monitor: monitor(),
+      dataToProcess: dataToProcess,
+      rootCause: "Host CPU utilization is above 90%",
+      autoResolveCriteriaInstanceIdIncidentIdsDictionary: NO_AUTO_RESOLVE,
+      matchesPerSeries: [
+        series({ "resource.vmware.vcenter.name": "vcsa" }, "fp-1"),
+      ],
+      props: {},
+    });
+
+    expect(idsOn(createdIncidents[0]!.vmwareVCenters).sort()).toEqual([
+      "vcsa-from-label",
+      "vcsa-from-step-config",
+    ]);
+  });
+
+  it("still attaches the step-config vCenter to an ungrouped incident", async () => {
+    /*
+     * The shipped VMware templates group by the vSphere object's own
+     * attribute, never by the vCenter, so the vCenter link on their
+     * incidents comes ONLY from the step config path.
+     */
+    resourceContext = {
+      ...emptyResourceContext(),
+      vmwareVCenterIds: ["vcsa-1"],
+    };
+
+    await MonitorIncident.criteriaMetCreateIncidentsAndUpdateMonitorStatus({
+      criteriaInstance: criteriaInstance(),
+      monitor: monitor(),
+      dataToProcess: dataToProcess,
+      rootCause: "Datastore capacity is above 90%",
+      autoResolveCriteriaInstanceIdIncidentIdsDictionary: NO_AUTO_RESOLVE,
+      props: {},
+    });
+
+    expect(idsOn(createdIncidents[0]!.vmwareVCenters)).toEqual(["vcsa-1"]);
+    expect(VMwareVCenterService.findBy).not.toHaveBeenCalled();
+  });
+
   it("links the service an ungrouped metric monitor is scoped to", async () => {
     /*
      * THE REPORTED BUG. The alert twin of this came from a Metrics monitor whose only

package/Tests/Server/Utils/Monitor/MonitorMaintenanceSuppression.test.ts

@@ -14,6 +14,7 @@ function emptyMaintained(): MaintainedResourceKeys {
     podmanHosts: { ids: new Set<string>(), names: new Set<string>() },
     kubernetesClusters: { ids: new Set<string>(), names: new Set<string>() },
     proxmoxClusters: { ids: new Set<string>(), names: new Set<string>() },
+    vmwareVCenters: { ids: new Set<string>(), names: new Set<string>() },
     cephClusters: { ids: new Set<string>(), names: new Set<string>() },
     dockerSwarmClusters: { ids: new Set<string>(), names: new Set<string>() },
     iotFleets: { ids: new Set<string>(), names: new Set<string>() },
@@ -108,6 +109,37 @@ describe("SeriesResourceLabels", () => {
       expect(refs.cephClusterNames).toEqual(["ceph-1"]);
     });
 
+    it("maps vmware vcenter name keys (prefixed and unprefixed)", () => {
+      const refs: SeriesResourceRefs = SeriesResourceLabels.extractResourceRefs(
+        {
+          "resource.vmware.vcenter.name": "vcsa-1",
+        },
+      );
+      expect(refs.vmwareVCenterNames).toEqual(["vcsa-1"]);
+
+      const refsUnprefixed: SeriesResourceRefs =
+        SeriesResourceLabels.extractResourceRefs({
+          "vmware.vcenter.name": "vcsa-2",
+        });
+      expect(refsUnprefixed.vmwareVCenterNames).toEqual(["vcsa-2"]);
+    });
+
+    it("does not read a vSphere object attribute as the vCenter identity", () => {
+      /*
+       * The shipped VMware templates group by `resource.vcenter.host.name`
+       * / `resource.vcenter.vm.name`; those name an ESXi host or a VM,
+       * not the vCenter, and must never resolve to a VMwareVCenter row.
+       */
+      const refs: SeriesResourceRefs = SeriesResourceLabels.extractResourceRefs(
+        {
+          "resource.vcenter.host.name": "esx-01",
+          "resource.vcenter.vm.name": "web-01",
+          "resource.vcenter.cluster.name": "prod-cluster",
+        },
+      );
+      expect(refs.vmwareVCenterNames).toEqual([]);
+    });
+
     it("maps iot fleet name keys (prefixed and unprefixed)", () => {
       const refs: SeriesResourceRefs = SeriesResourceLabels.extractResourceRefs(
         {
@@ -237,6 +269,34 @@ describe("MonitorMaintenanceSuppression.getSuppressedFingerprintsForMaintainedRe
     expect(Array.from(result)).toEqual(["fpSwarm"]);
   });
 
+  it("suppresses a vmware series whose vCenter is under maintenance", () => {
+    /*
+     * Same contract for vCenters: a user-built monitor grouped by
+     * `vmware.vcenter.name` must go quiet while the vCenter is attached
+     * to an ongoing maintenance window. The shipped templates group by
+     * host / VM / datastore instead and rely on the step-config path.
+     */
+    const maintained: MaintainedResourceKeys = emptyMaintained();
+    maintained.vmwareVCenters.names.add("vcsa-prod");
+
+    const result: Set<string> =
+      MonitorMaintenanceSuppression.getSuppressedFingerprintsForMaintainedResources(
+        {
+          matchesPerSeries: [
+            series("fpVCenter", {
+              "resource.vmware.vcenter.name": "vcsa-prod",
+            }),
+            series("fpClear", {
+              "resource.vmware.vcenter.name": "vcsa-staging",
+            }),
+          ],
+          maintained,
+        },
+      );
+
+    expect(Array.from(result)).toEqual(["fpVCenter"]);
+  });
+
   it("does not cross-match resource types that happen to share a name", () => {
     /*
      * A service named the same string as the breaching host must not