@oneuptime/common 13.0.0 → 13.0.3

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

package/Types/Monitor/MonitorStep.ts

@@ -72,6 +72,9 @@ import MonitorStepPodmanMonitor, {
 import MonitorStepProxmoxMonitor, {
   MonitorStepProxmoxMonitorUtil,
 } from "./MonitorStepProxmoxMonitor";
+import MonitorStepVMwareMonitor, {
+  MonitorStepVMwareMonitorUtil,
+} from "./MonitorStepVMwareMonitor";
 import MonitorStepDockerSwarmMonitor, {
   MonitorStepDockerSwarmMonitorUtil,
 } from "./MonitorStepDockerSwarmMonitor";
@@ -84,6 +87,7 @@ import MonitorStepIoTMonitor, {
 import MetricsViewConfig from "../Metrics/MetricsViewConfig";
 import MetricQueryConfigData from "../Metrics/MetricQueryConfigData";
 import Zod, { ZodSchema } from "../../Utils/Schema/Zod";
+import MonitorTemplateSyncFieldUtil from "./MonitorTemplateSyncField";
 
 /*
  * Caps and defaults for per-step request timeout and retry settings.
@@ -120,6 +124,8 @@ export const clampMonitorRetryCount: (value: number) => number = (
 
 export interface MonitorStepType {
   id: string;
+  // Template policy: keep these fields from each linked monitor during sync.
+  doNotSyncFields?: Array<string> | undefined;
   monitorDestination?: URL | IP | Hostname | undefined;
 
   monitorCriteria: MonitorCriteria;
@@ -228,6 +234,9 @@ export interface MonitorStepType {
   // Proxmox monitor
   proxmoxMonitor?: MonitorStepProxmoxMonitor | undefined;
 
+  // VMware monitor
+  vmwareMonitor?: MonitorStepVMwareMonitor | undefined;
+
   // Docker Swarm monitor
   dockerSwarmMonitor?: MonitorStepDockerSwarmMonitor | undefined;
 
@@ -282,6 +291,7 @@ export default class MonitorStep extends DatabaseProperty {
       hostMonitor: undefined,
       podmanMonitor: undefined,
       proxmoxMonitor: undefined,
+      vmwareMonitor: undefined,
       dockerSwarmMonitor: undefined,
       cephMonitor: undefined,
       iotMonitor: undefined,
@@ -368,6 +378,7 @@ export default class MonitorStep extends DatabaseProperty {
       hostMonitor: undefined,
       podmanMonitor: undefined,
       proxmoxMonitor: undefined,
+      vmwareMonitor: undefined,
       dockerSwarmMonitor: undefined,
       cephMonitor: undefined,
       iotMonitor: undefined,
@@ -403,6 +414,7 @@ export default class MonitorStep extends DatabaseProperty {
       data.hostMonitor?.metricViewConfig ||
       data.podmanMonitor?.metricViewConfig ||
       data.proxmoxMonitor?.metricViewConfig ||
+      data.vmwareMonitor?.metricViewConfig ||
       data.cephMonitor?.metricViewConfig
     );
   }
@@ -684,6 +696,13 @@ export default class MonitorStep extends DatabaseProperty {
     return this;
   }
 
+  public setVMwareMonitor(
+    vmwareMonitor: MonitorStepVMwareMonitor,
+  ): MonitorStep {
+    this.data!.vmwareMonitor = vmwareMonitor;
+    return this;
+  }
+
   public setDockerSwarmMonitor(
     dockerSwarmMonitor: MonitorStepDockerSwarmMonitor,
   ): MonitorStep {
@@ -741,6 +760,7 @@ export default class MonitorStep extends DatabaseProperty {
         hostMonitor: undefined,
         podmanMonitor: undefined,
         proxmoxMonitor: undefined,
+        vmwareMonitor: undefined,
         dockerSwarmMonitor: undefined,
         cephMonitor: undefined,
         iotMonitor: undefined,
@@ -756,6 +776,15 @@ export default class MonitorStep extends DatabaseProperty {
       return "Monitor Step is required.";
     }
 
+    try {
+      MonitorTemplateSyncFieldUtil.parse(
+        value.data.doNotSyncFields,
+        monitorType,
+      );
+    } catch (error) {
+      return (error as Error).message;
+    }
+
     // If the monitor type is incoming request, then the monitor destination is not required
     if (
       !value.data.monitorDestination &&
@@ -996,6 +1025,16 @@ export default class MonitorStep extends DatabaseProperty {
       }
     }
 
+    if (monitorType === MonitorType.VMware) {
+      if (!value.data.vmwareMonitor) {
+        return "VMware monitor configuration is required";
+      }
+
+      if (!value.data.vmwareMonitor.vcenterIdentifier) {
+        return "vCenter is required";
+      }
+    }
+
     if (monitorType === MonitorType.DockerSwarm) {
       if (!value.data.dockerSwarmMonitor) {
         return "Docker Swarm monitor configuration is required";
@@ -1035,24 +1074,26 @@ export default class MonitorStep extends DatabaseProperty {
         _type: ObjectType.MonitorStep,
         value: {
           id: this.data.id,
+          doNotSyncFields: MonitorTemplateSyncFieldUtil.parse(
+            this.data.doNotSyncFields,
+          ),
           monitorDestination:
             this.data?.monitorDestination?.toJSON() || undefined,
-          doNotFollowRedirects: this.data.doNotFollowRedirects || undefined,
-          allowSelfSignedCertificates:
-            this.data.allowSelfSignedCertificates || undefined,
-          tlsClientCertificate: this.data.tlsClientCertificate || undefined,
-          tlsClientKey: this.data.tlsClientKey || undefined,
-          tlsClientKeyPassphrase: this.data.tlsClientKeyPassphrase || undefined,
+          doNotFollowRedirects: this.data.doNotFollowRedirects,
+          allowSelfSignedCertificates: this.data.allowSelfSignedCertificates,
+          tlsClientCertificate: this.data.tlsClientCertificate,
+          tlsClientKey: this.data.tlsClientKey,
+          tlsClientKeyPassphrase: this.data.tlsClientKeyPassphrase,
           monitorDestinationPort:
             this.data?.monitorDestinationPort?.toJSON() || undefined,
           monitorCriteria: this.data.monitorCriteria.toJSON(),
           requestType: this.data.requestType,
           requestHeaders: this.data.requestHeaders || undefined,
-          requestBody: this.data.requestBody || undefined,
-          customCode: this.data.customCode || undefined,
+          requestBody: this.data.requestBody,
+          customCode: this.data.customCode,
           screenSizeTypes: this.data.screenSizeTypes || undefined,
           browserTypes: this.data.browserTypes || undefined,
-          retryCountOnError: this.data.retryCountOnError || undefined,
+          retryCountOnError: this.data.retryCountOnError,
           requestTimeoutInMs: this.data.requestTimeoutInMs || undefined,
           retryCount:
             this.data.retryCount === undefined
@@ -1134,6 +1175,9 @@ export default class MonitorStep extends DatabaseProperty {
           proxmoxMonitor: this.data.proxmoxMonitor
             ? MonitorStepProxmoxMonitorUtil.toJSON(this.data.proxmoxMonitor)
             : undefined,
+          vmwareMonitor: this.data.vmwareMonitor
+            ? MonitorStepVMwareMonitorUtil.toJSON(this.data.vmwareMonitor)
+            : undefined,
           dockerSwarmMonitor: this.data.dockerSwarmMonitor
             ? MonitorStepDockerSwarmMonitorUtil.toJSON(
                 this.data.dockerSwarmMonitor,
@@ -1220,15 +1264,18 @@ export default class MonitorStep extends DatabaseProperty {
 
     monitorStep.data = JSONFunctions.deserialize({
       id: json["id"] as string,
+      doNotSyncFields: MonitorTemplateSyncFieldUtil.parse(
+        json["doNotSyncFields"],
+      ),
       monitorDestination: monitorDestination || undefined,
-      doNotFollowRedirects: json["doNotFollowRedirects"] || undefined,
+      doNotFollowRedirects: json["doNotFollowRedirects"] ?? undefined,
       allowSelfSignedCertificates:
-        json["allowSelfSignedCertificates"] || undefined,
+        json["allowSelfSignedCertificates"] ?? undefined,
       tlsClientCertificate:
-        (json["tlsClientCertificate"] as string) || undefined,
-      tlsClientKey: (json["tlsClientKey"] as string) || undefined,
+        (json["tlsClientCertificate"] as string) ?? undefined,
+      tlsClientKey: (json["tlsClientKey"] as string) ?? undefined,
       tlsClientKeyPassphrase:
-        (json["tlsClientKeyPassphrase"] as string) || undefined,
+        (json["tlsClientKeyPassphrase"] as string) ?? undefined,
       monitorDestinationPort: monitorDestinationPort || undefined,
       monitorCriteria: MonitorCriteria.fromJSON(
         json["monitorCriteria"] as JSONObject,
@@ -1236,12 +1283,12 @@ export default class MonitorStep extends DatabaseProperty {
       requestType: (json["requestType"] as HTTPMethod) || HTTPMethod.GET,
       requestHeaders:
         (json["requestHeaders"] as Dictionary<string>) || undefined,
-      requestBody: (json["requestBody"] as string) || undefined,
-      customCode: (json["customCode"] as string) || undefined,
+      requestBody: (json["requestBody"] as string) ?? undefined,
+      customCode: (json["customCode"] as string) ?? undefined,
       screenSizeTypes:
         (json["screenSizeTypes"] as Array<ScreenSizeType>) || undefined,
       browserTypes: (json["browserTypes"] as Array<BrowserType>) || undefined,
-      retryCountOnError: (json["retryCountOnError"] as number) || undefined,
+      retryCountOnError: (json["retryCountOnError"] as number) ?? undefined,
       requestTimeoutInMs: (json["requestTimeoutInMs"] as number) || undefined,
       retryCount:
         json["retryCount"] === undefined || json["retryCount"] === null
@@ -1343,6 +1390,9 @@ export default class MonitorStep extends DatabaseProperty {
       proxmoxMonitor: json["proxmoxMonitor"]
         ? (json["proxmoxMonitor"] as JSONObject)
         : undefined,
+      vmwareMonitor: json["vmwareMonitor"]
+        ? (json["vmwareMonitor"] as JSONObject)
+        : undefined,
       dockerSwarmMonitor: json["dockerSwarmMonitor"]
         ? (json["dockerSwarmMonitor"] as JSONObject)
         : undefined,
@@ -1362,6 +1412,16 @@ export default class MonitorStep extends DatabaseProperty {
       _type: Zod.literal(ObjectType.MonitorStep),
       value: Zod.object({
         id: Zod.string(),
+        doNotSyncFields: Zod.array(
+          Zod.string().refine((value: string): boolean => {
+            try {
+              MonitorTemplateSyncFieldUtil.parse([value]);
+              return true;
+            } catch {
+              return false;
+            }
+          }, "Unsupported do not sync field"),
+        ).optional(),
         monitorDestination: Zod.any().optional(),
         monitorCriteria: Zod.any(),
         requestType: Zod.any(),
@@ -1397,6 +1457,7 @@ export default class MonitorStep extends DatabaseProperty {
         hostMonitor: Zod.any().optional(),
         podmanMonitor: Zod.any().optional(),
         proxmoxMonitor: Zod.any().optional(),
+        vmwareMonitor: Zod.any().optional(),
         dockerSwarmMonitor: Zod.any().optional(),
         cephMonitor: Zod.any().optional(),
         iotMonitor: Zod.any().optional(),

package/Types/Monitor/MonitorStepMetricViewConfigUtil.ts

@@ -22,6 +22,7 @@ const METRIC_VIEW_CONFIG_KEYS: Array<keyof MonitorStepType> = [
   "dockerSwarmMonitor",
   "podmanMonitor",
   "proxmoxMonitor",
+  "vmwareMonitor",
   "cephMonitor",
   "iotMonitor",
 ];

package/Types/Monitor/MonitorStepVMwareMonitor.ts

@@ -0,0 +1,127 @@
+import { JSONObject } from "../JSON";
+import MetricsViewConfig from "../Metrics/MetricsViewConfig";
+import RollingTime from "../RollingTime/RollingTime";
+
+/**
+ * The kind of vSphere object a metric series belongs to.
+ *
+ * The OpenTelemetry Collector `vcenter` receiver emits one OTLP resource per
+ * vSphere object and identifies it through RESOURCE attributes
+ * (`vcenter.datacenter.name`, `vcenter.cluster.name`, `vcenter.host.name`,
+ * `vcenter.vm.name` / `vcenter.vm.id`, `vcenter.datastore.name`,
+ * `vcenter.resource_pool.inventory_path`). There is no agent-stamped scope
+ * attribute the way Proxmox has `pve.scope`, so this enum is a catalog /
+ * picker hint that says which identity attributes a metric carries — it is
+ * never sent to ClickHouse as a filter itself.
+ */
+export enum VMwareResourceScope {
+  VCenter = "vcenter",
+  Datacenter = "datacenter",
+  Cluster = "cluster",
+  Host = "host",
+  VirtualMachine = "vm",
+  Datastore = "datastore",
+  ResourcePool = "resource_pool",
+}
+
+/**
+ * The inventory row kinds `VMwareResource.kind` can hold. Kept next to the
+ * scope enum so the ingest scan, the inventory model description and the
+ * dashboard all reference the same literal strings.
+ *
+ * VM templates are VirtualMachine rows with `isTemplate = true`; vApps are
+ * not an inventory kind (vApp membership is a VM attribute only).
+ */
+export enum VMwareResourceKind {
+  Datacenter = "Datacenter",
+  Cluster = "Cluster",
+  Host = "Host",
+  VirtualMachine = "VirtualMachine",
+  Datastore = "Datastore",
+  ResourcePool = "ResourcePool",
+}
+
+/*
+ * Filter contract: every filter below is an equality on an OTel RESOURCE
+ * attribute, which OtelMetricsIngestService stores `resource.`-prefixed in
+ * ClickHouse. The monitor worker maps each field to its prefixed attribute
+ * (the arrow in each comment) and always adds
+ * `resource.vmware.vcenter.name = vcenterIdentifier` on top.
+ *
+ * Datapoint attributes (`disk_state`, `power_state`, `status`, `effective`,
+ * `direction`, `object`, `type`) are NOT filters here — they are per-query
+ * attribute filters on the metric query itself, exactly like the Kubernetes
+ * templates use them.
+ */
+export interface VMwareResourceFilters {
+  /** → `resource.vcenter.datacenter.name` equality. */
+  datacenterName?: string | undefined;
+  /**
+   * → `resource.vcenter.cluster.name` equality. Present on cluster, host,
+   * VM and resource-pool series when the object sits inside a cluster;
+   * absent for standalone ESXi hosts and the objects on them.
+   */
+  clusterName?: string | undefined;
+  /**
+   * → `resource.vcenter.host.name` equality. Scopes to the ESXi host's own
+   * series AND to the series of every VM it runs (the receiver stamps the
+   * parent host on VM resources), so a host filter alone still fans out
+   * across the VMs of that host — combine with `vmName` to target one VM.
+   */
+  hostName?: string | undefined;
+  /** → `resource.vcenter.vm.name` equality. */
+  vmName?: string | undefined;
+  /** → `resource.vcenter.datastore.name` equality. */
+  datastoreName?: string | undefined;
+  /**
+   * → `resource.vcenter.resource_pool.inventory_path` equality. The
+   * inventory path (`/DC/host/Cluster/Resources/pool`) is used rather than
+   * the pool name because pool names are only unique within a parent.
+   */
+  resourcePoolPath?: string | undefined;
+}
+
+export default interface MonitorStepVMwareMonitor {
+  /**
+   * The `vmware.vcenter.name` resource attribute the agent stamps on every
+   * metric — one value per vCenter Server (or standalone ESXi host) the
+   * agent connects to.
+   */
+  vcenterIdentifier: string;
+  resourceFilters: VMwareResourceFilters;
+  metricViewConfig: MetricsViewConfig;
+  rollingTime: RollingTime;
+}
+
+export class MonitorStepVMwareMonitorUtil {
+  public static getDefault(): MonitorStepVMwareMonitor {
+    return {
+      vcenterIdentifier: "",
+      resourceFilters: {},
+      metricViewConfig: {
+        queryConfigs: [],
+        formulaConfigs: [],
+      },
+      /*
+       * The VMware Agent polls vCenter every VCENTER_COLLECTION_INTERVAL
+       * (2 minutes by default) and the vcenter receiver emits ONE sample per
+       * object per collection, so the 1-minute window the 30-second Proxmox
+       * and Kubernetes agents default to would hold no sample on roughly
+       * every other evaluation — a hand-built monitor would flip between
+       * "no criteria met" and firing every tick. Default to 5 minutes (at
+       * least two collections) so the step form, the metric picker, the API
+       * and Terraform all seed the same safe window; the shipped templates
+       * hard-code 5 / 15 minutes for the same reason.
+       */
+      rollingTime: RollingTime.Past5Minutes,
+    };
+  }
+
+  public static fromJSON(json: JSONObject): MonitorStepVMwareMonitor {
+    return json as any as MonitorStepVMwareMonitor;
+  }
+
+  public static toJSON(monitor: MonitorStepVMwareMonitor): JSONObject {
+    return monitor as any as JSONObject;
+  }
+}