@oneuptime/common 13.0.0 → 13.0.1

package/Types/Dashboard/DashboardTemplates.ts

@@ -36,6 +36,7 @@ export enum DashboardTemplateType {
   KubernetesCost = "KubernetesCost",
   Host = "Host",
   Proxmox = "Proxmox",
+  VMware = "VMware",
   Ceph = "Ceph",
   DockerSwarm = "DockerSwarm",
   Metrics = "Metrics",
@@ -151,6 +152,14 @@ export const DashboardTemplates: Array<DashboardTemplate> = [
     icon: IconProp.ServerStack,
     category: DashboardTemplateCategory.Infrastructure,
   },
+  {
+    type: DashboardTemplateType.VMware,
+    name: "VMware Dashboard",
+    description:
+      "Live ESXi host and virtual machine inventories, host CPU/memory utilization, datastore capacity, CPU ready and memory ballooning trends, and vCenter logs.",
+    icon: IconProp.VMware,
+    category: DashboardTemplateCategory.Infrastructure,
+  },
   {
     type: DashboardTemplateType.Ceph,
     name: "Ceph Dashboard",
@@ -693,6 +702,60 @@ function createProxmoxGuestListComponent(data: {
   };
 }
 
+function createVMwareHostListComponent(data: {
+  title: string;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  maxRows?: number;
+}): DashboardBaseComponent {
+  return {
+    _type: ObjectType.DashboardComponent,
+    componentType: DashboardComponentType.VMwareHostList,
+    componentId: ObjectID.generate(),
+    topInDashboardUnits: data.top,
+    leftInDashboardUnits: data.left,
+    widthInDashboardUnits: data.width,
+    heightInDashboardUnits: data.height,
+    minHeightInDashboardUnits: 3,
+    minWidthInDashboardUnits: 4,
+    arguments: {
+      title: data.title,
+      maxRows: data.maxRows ?? 20,
+    },
+  };
+}
+
+function createVMwareVirtualMachineListComponent(data: {
+  title: string;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  maxRows?: number;
+  powerStateFilter?: string;
+  templateFilter?: string;
+}): DashboardBaseComponent {
+  return {
+    _type: ObjectType.DashboardComponent,
+    componentType: DashboardComponentType.VMwareVirtualMachineList,
+    componentId: ObjectID.generate(),
+    topInDashboardUnits: data.top,
+    leftInDashboardUnits: data.left,
+    widthInDashboardUnits: data.width,
+    heightInDashboardUnits: data.height,
+    minHeightInDashboardUnits: 3,
+    minWidthInDashboardUnits: 4,
+    arguments: {
+      title: data.title,
+      maxRows: data.maxRows ?? 20,
+      powerStateFilter: data.powerStateFilter,
+      templateFilter: data.templateFilter,
+    },
+  };
+}
+
 function createDockerSwarmNodeListComponent(data: {
   title: string;
   top: number;
@@ -3189,6 +3252,255 @@ function createProxmoxDashboardConfig(): DashboardViewConfig {
   };
 }
 
+function createVMwareDashboardConfig(): DashboardViewConfig {
+  /*
+   * Layout notes:
+   *
+   * - Host / VM counts come from the Postgres inventory list widgets
+   *   (VMwareResource), never from Sum-of-gauge Value widgets. The
+   *   vcenter receiver's count metrics (vcenter.datacenter.host.count,
+   *   vcenter.cluster.vm.count, ...) fan out over status x power_state
+   *   attributes and re-emit every scrape, so summing them across the
+   *   dashboard window multiplies (buckets x scrapes) — the same failure
+   *   the Kubernetes / Proxmox templates document — and template metric
+   *   widgets cannot filter on datapoint attributes to pick one bucket.
+   *   The list-widget headers show the true current counts; the VM list
+   *   hides templates so its header counts real virtual machines.
+   *
+   * - Every metric here is a per-object gauge the receiver already
+   *   reports in its final unit (utilization in %, readiness in %,
+   *   throughput in KiBy/s, ballooned memory in MiBy), so Avg is the
+   *   right aggregation for the temperature tiles and trend charts and
+   *   nothing needs transformAsRate.
+   *
+   * - Ballooned memory is charted with Max rather than Avg: one VM under
+   *   balloon pressure is the signal, and averaging it across a fleet of
+   *   healthy VMs would hide it.
+   *
+   * - Host charts fan out via groupByAttributeKeys on the resource's own
+   *   identity attribute so one line per ESXi host is drawn; identity for
+   *   vcenter metrics lives in RESOURCE attributes, hence the `resource.`
+   *   prefix (same convention as the vCenter variable below).
+   */
+  const components: Array<DashboardBaseComponent> = [
+    // Row 0: Title
+    createTextComponent({
+      text: "VMware Dashboard",
+      top: 0,
+      left: 0,
+      width: 12,
+      height: 1,
+      isBold: true,
+    }),
+
+    // Rows 1-4: Live inventory from the Postgres snapshot
+    createVMwareHostListComponent({
+      title: "Hosts",
+      top: 1,
+      left: 0,
+      width: 6,
+      height: 4,
+      maxRows: 25,
+    }),
+    createVMwareVirtualMachineListComponent({
+      title: "Virtual Machines",
+      top: 1,
+      left: 6,
+      width: 6,
+      height: 4,
+      maxRows: 25,
+      templateFilter: "exclude",
+    }),
+
+    // Row 5: Section header
+    createTextComponent({
+      text: "Utilization",
+      top: 5,
+      left: 0,
+      width: 12,
+      height: 1,
+      isBold: true,
+    }),
+
+    /*
+     * Row 6: Fleet-wide temperature tiles. All four are percentages the
+     * receiver reports directly, and all are "higher = worse".
+     */
+    createValueComponent({
+      title: "Host CPU (avg %)",
+      top: 6,
+      left: 0,
+      width: 3,
+      metricConfig: {
+        metricName: "vcenter.host.cpu.utilization",
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+    createValueComponent({
+      title: "Host Memory (avg %)",
+      top: 6,
+      left: 3,
+      width: 3,
+      metricConfig: {
+        metricName: "vcenter.host.memory.utilization",
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+    createValueComponent({
+      title: "Datastore Used (avg %)",
+      top: 6,
+      left: 6,
+      width: 3,
+      metricConfig: {
+        metricName: "vcenter.datastore.disk.utilization",
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+    createValueComponent({
+      title: "VM CPU Ready (avg %)",
+      top: 6,
+      left: 9,
+      width: 3,
+      metricConfig: {
+        metricName: "vcenter.vm.cpu.readiness",
+        aggregationType: MetricsAggregationType.Avg,
+      },
+      trendDirection: DashboardValueTrendDirection.HigherIsWorse,
+    }),
+
+    // Rows 7-9: Per-host CPU and memory trends
+    createChartComponent({
+      title: "Host CPU Utilization",
+      chartType: DashboardChartType.Line,
+      top: 7,
+      left: 0,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "vcenter.host.cpu.utilization",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "CPU %",
+        legendUnit: "%",
+        groupByAttributeKeys: ["resource.vcenter.host.name"],
+      },
+    }),
+    createChartComponent({
+      title: "Host Memory Utilization",
+      chartType: DashboardChartType.Line,
+      top: 7,
+      left: 6,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "vcenter.host.memory.utilization",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Memory %",
+        legendUnit: "%",
+        groupByAttributeKeys: ["resource.vcenter.host.name"],
+      },
+    }),
+
+    // Row 10: Section header
+    createTextComponent({
+      text: "Capacity & Contention",
+      top: 10,
+      left: 0,
+      width: 12,
+      height: 1,
+      isBold: true,
+    }),
+
+    // Rows 11-13: Datastore capacity and VM CPU contention
+    createChartComponent({
+      title: "Datastore Utilization",
+      chartType: DashboardChartType.Line,
+      top: 11,
+      left: 0,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "vcenter.datastore.disk.utilization",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "Used %",
+        legendUnit: "%",
+        groupByAttributeKeys: ["resource.vcenter.datastore.name"],
+      },
+    }),
+    createChartComponent({
+      title: "VM CPU Ready (avg across VMs)",
+      chartType: DashboardChartType.Line,
+      top: 11,
+      left: 6,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "vcenter.vm.cpu.readiness",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "CPU ready %",
+        legendUnit: "%",
+      },
+    }),
+
+    // Rows 14-16: Memory pressure and host network throughput
+    createChartComponent({
+      title: "VM Memory Ballooned (max per VM)",
+      chartType: DashboardChartType.Area,
+      top: 14,
+      left: 0,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "vcenter.vm.memory.ballooned",
+        aggregationType: MetricsAggregationType.Max,
+        legend: "Ballooned MiB",
+        legendUnit: "MiB",
+      },
+    }),
+    createChartComponent({
+      title: "Host Network Throughput (avg per host)",
+      chartType: DashboardChartType.Area,
+      top: 14,
+      left: 6,
+      width: 6,
+      height: 3,
+      metricConfig: {
+        metricName: "vcenter.host.network.throughput",
+        aggregationType: MetricsAggregationType.Avg,
+        legend: "KiB/s",
+        legendUnit: "KiB/s",
+        groupByAttributeKeys: ["resource.vcenter.host.name"],
+      },
+    }),
+
+    // Rows 17-19: Logs (ESXi syslog forwarded through the agent's syslog receiver)
+    createLogStreamComponent({
+      title: "vCenter Logs",
+      top: 17,
+      left: 0,
+      width: 12,
+      height: 3,
+    }),
+  ];
+
+  const variables: Array<DashboardVariable> = [
+    createTelemetryAttributeVariable({
+      name: "vcenter",
+      label: "vCenter",
+      attributeKey: "resource.vmware.vcenter.name",
+    }),
+  ];
+
+  return {
+    _type: ObjectType.DashboardViewConfig,
+    components,
+    variables,
+    heightInDashboardUnits: Math.max(DashboardSize.heightInDashboardUnits, 20),
+  };
+}
+
 function createDockerSwarmDashboardConfig(): DashboardViewConfig {
   /*
    * Layout notes:
@@ -3824,6 +4136,8 @@ export function getTemplateConfig(
       return createHostDashboardConfig();
     case DashboardTemplateType.Proxmox:
       return createProxmoxDashboardConfig();
+    case DashboardTemplateType.VMware:
+      return createVMwareDashboardConfig();
     case DashboardTemplateType.Ceph:
       return createCephDashboardConfig();
     case DashboardTemplateType.DockerSwarm:

package/Types/Docs/DocsLanguage.ts

@@ -31,6 +31,7 @@ export const SUPPORTED_DOCS_LANGUAGES: Array<DocsLanguage> = [
     englishName: "Chinese (Traditional)",
   },
   { code: "hi", nativeName: "हिन्दी", englishName: "Hindi" },
+  { code: "fa", nativeName: "فارسی", englishName: "Persian" },
 ];
 
 export const SUPPORTED_DOCS_LANGUAGE_CODES: Array<string> =

package/Types/Exception/EgressGuardException.ts

@@ -0,0 +1,65 @@
+import BadDataException from "./BadDataException";
+
+/*
+ * Why the egress guard refused a target.
+ *
+ * The guard deliberately SANITIZES its message for tenant-facing callers (see
+ * EgressGuardOptions.includeResolvedAddressInError): a DNS failure and an
+ * address-policy rejection produce one byte-identical sentence, because a
+ * tenant who can tell them apart on a shared probe can enumerate internal DNS
+ * names. That is correct, and this type does not weaken it.
+ *
+ * What it fixes is the collateral damage. Callers downstream had nothing but
+ * that sanitized string to reason about, so API.getRequestFailedDetails matched
+ * none of its patterns and reported monitor failures as "Unknown" with no
+ * actionable detail. Carrying the STAGE on the exception restores the one bit
+ * every caller legitimately needs without reopening the oracle: when detail is
+ * suppressed, both the DNS branch and the address-policy branch report
+ * `Unreachable`, so nothing observable distinguishes them.
+ */
+export enum EgressFailureReason {
+  /*
+   * The target is structurally unusable: no host, an unparseable URL, or a
+   * scheme other than http/https. This is the tenant's own configuration
+   * echoed back and never reveals anything about the probe's network.
+   */
+  InvalidTarget = "InvalidTarget",
+
+  /*
+   * Detail-suppressed merge of "the resolver failed or returned nothing" and
+   * "the target resolves to an address policy forbids". Deliberately ONE
+   * value: these two must stay indistinguishable to tenant-facing callers.
+   */
+  Unreachable = "Unreachable",
+
+  // Detail permitted: the resolver threw, or returned no addresses at all.
+  ResolutionFailed = "ResolutionFailed",
+
+  // Detail permitted: an address the target resolves to is not allowed.
+  AddressBlocked = "AddressBlocked",
+}
+
+/*
+ * Extends BadDataException rather than replacing it so every existing
+ * `instanceof BadDataException` check — including the security-relevant
+ * fail-fast paths in the probe monitors — keeps behaving exactly as before.
+ */
+export default class EgressGuardException extends BadDataException {
+  public readonly reason: EgressFailureReason;
+
+  public constructor(message: string, reason: EgressFailureReason) {
+    super(message);
+    this.reason = reason;
+  }
+
+  /*
+   * True when the refusal is about REACHING the target rather than the target
+   * being malformed. Monitors treat these like any other network failure — a
+   * probe whose own resolver has died must not be believed when it says every
+   * monitor is down — whereas InvalidTarget is a configuration error that has
+   * to surface immediately and unconditionally.
+   */
+  public isTargetUnreachable(): boolean {
+    return this.reason !== EgressFailureReason.InvalidTarget;
+  }
+}

package/Types/Icon/IconProp.ts

@@ -328,6 +328,7 @@ enum IconProp {
   DockerSwarm = "DockerSwarm",
   Podman = "Podman",
   Proxmox = "Proxmox",
+  VMware = "VMware",
   IoT = "IoT",
   Ceph = "Ceph",
   Gauge = "Gauge",

package/Types/Monitor/MetricMonitor/MetricMonitorResponse.ts

@@ -46,6 +46,41 @@ export interface ProxmoxResourceBreakdown {
   attributes: Dictionary<string>;
 }
 
+/**
+ * One vSphere object in a VMware monitor's per-series breakdown. Every
+ * field except `metricValue` is an OTel RESOURCE attribute the vcenter
+ * receiver stamps (stored `resource.`-prefixed in ClickHouse); which ones
+ * are present depends on the object kind the series describes.
+ */
+export interface VMwareAffectedResource {
+  /** `resource.vcenter.datacenter.name` — present on every series. */
+  datacenterName?: string | undefined;
+  /** `resource.vcenter.cluster.name` — only when the object is inside a cluster. */
+  clusterName?: string | undefined;
+  /** `resource.vcenter.host.name` — the ESXi host, or a VM's parent host. */
+  hostName?: string | undefined;
+  /** `resource.vcenter.vm.name` — virtual machine series only. */
+  vmName?: string | undefined;
+  /** `resource.vcenter.vm.id` — the VM's instance UUID (VM series only). */
+  vmId?: string | undefined;
+  /** `resource.vcenter.datastore.name` — datastore series only. */
+  datastoreName?: string | undefined;
+  /** `resource.vcenter.resource_pool.name` — resource pool (and pooled VM) series. */
+  resourcePoolName?: string | undefined;
+  /** `resource.vcenter.resource_pool.inventory_path` — the pool's unique path. */
+  resourcePoolPath?: string | undefined;
+  metricValue: number;
+}
+
+export interface VMwareResourceBreakdown {
+  /** The `vmware.vcenter.name` the agent stamps — one per vCenter. */
+  vcenterName: string;
+  metricName: string;
+  metricFriendlyName: string;
+  affectedResources: Array<VMwareAffectedResource>;
+  attributes: Dictionary<string>;
+}
+
 export interface CephAffectedResource {
   /** `ceph_daemon` datapoint label, e.g. "osd.3", "mon.a". */
   daemon?: string | undefined;
@@ -95,6 +130,7 @@ export default interface MetricMonitorResponse {
   evaluationSummary?: MonitorEvaluationSummary | undefined;
   kubernetesResourceBreakdown?: KubernetesResourceBreakdown | undefined;
   proxmoxResourceBreakdown?: ProxmoxResourceBreakdown | undefined;
+  vmwareResourceBreakdown?: VMwareResourceBreakdown | undefined;
   cephResourceBreakdown?: CephResourceBreakdown | undefined;
   dockerSwarmResourceBreakdown?: DockerSwarmResourceBreakdown | undefined;
   /**

package/Types/Monitor/MonitorCriteriaInstance.ts

@@ -114,6 +114,7 @@ export default class MonitorCriteriaInstance extends DatabaseProperty {
       monitorType === MonitorType.Podman ||
       monitorType === MonitorType.DockerSwarm ||
       monitorType === MonitorType.Proxmox ||
+      monitorType === MonitorType.VMware ||
       monitorType === MonitorType.Ceph ||
       monitorType === MonitorType.IoTDevice
     );