@oneuptime/common 11.4.1 → 11.5.0

package/Types/Monitor/MonitorMetricType.ts

@@ -24,6 +24,16 @@ enum MonitorMetricType {
   TimeToFirstByte = "oneuptime.monitor.http.time.to.first.byte",
   DownloadTime = "oneuptime.monitor.http.download.time",
 
+  /*
+   * Per-interface SNMP metrics. Emitted when interface monitoring is enabled
+   * on an SNMP monitor; one series per interface (interfaceName attribute).
+   */
+  SnmpInterfaceOperStatus = "oneuptime.monitor.snmp.interface.oper.status",
+  SnmpInterfaceInBitsPerSecond = "oneuptime.monitor.snmp.interface.in.bits.per.second",
+  SnmpInterfaceOutBitsPerSecond = "oneuptime.monitor.snmp.interface.out.bits.per.second",
+  SnmpInterfaceUtilizationPercent = "oneuptime.monitor.snmp.interface.utilization.percent",
+  SnmpInterfaceErrorsPerSecond = "oneuptime.monitor.snmp.interface.errors.per.second",
+
   /*
    * Extended server/VM metrics. Emitted when the agent payload contains them;
    * absent for older agents, which keeps the pipeline backwards-compatible.

package/Types/Monitor/MonitorStep.ts

@@ -29,6 +29,9 @@ import MonitorStepExceptionMonitor, {
 import MonitorStepProfileMonitor, {
   MonitorStepProfileMonitorUtil,
 } from "./MonitorStepProfileMonitor";
+import MonitorStepNetworkDeviceMonitor, {
+  MonitorStepNetworkDeviceMonitorUtil,
+} from "./MonitorStepNetworkDeviceMonitor";
 import MonitorStepSnmpMonitor, {
   MonitorStepSnmpMonitorUtil,
 } from "./MonitorStepSnmpMonitor";
@@ -168,9 +171,16 @@ export interface MonitorStepType {
   // Profile monitor
   profileMonitor?: MonitorStepProfileMonitor | undefined;
 
-  // SNMP monitor
+  /*
+   * SNMP config carrier. For Network Device monitors this is populated
+   * server-side (hydrated from the referenced NetworkDevice) when work is
+   * handed to probes — it is never set by users.
+   */
   snmpMonitor?: MonitorStepSnmpMonitor | undefined;
 
+  // Network Device monitor (references a NetworkDevice resource)
+  networkDeviceMonitor?: MonitorStepNetworkDeviceMonitor | undefined;
+
   // DNS monitor
   dnsMonitor?: MonitorStepDnsMonitor | undefined;
 
@@ -239,6 +249,7 @@ export default class MonitorStep extends DatabaseProperty {
       exceptionMonitor: undefined,
       profileMonitor: undefined,
       snmpMonitor: undefined,
+      networkDeviceMonitor: undefined,
       dnsMonitor: undefined,
       domainMonitor: undefined,
       dnssecMonitor: undefined,
@@ -289,6 +300,7 @@ export default class MonitorStep extends DatabaseProperty {
       exceptionMonitor: undefined,
       profileMonitor: undefined,
       snmpMonitor: undefined,
+      networkDeviceMonitor: undefined,
       dnsMonitor: undefined,
       domainMonitor: undefined,
       dnssecMonitor: undefined,
@@ -476,6 +488,13 @@ export default class MonitorStep extends DatabaseProperty {
     return this;
   }
 
+  public setNetworkDeviceMonitor(
+    networkDeviceMonitor: MonitorStepNetworkDeviceMonitor,
+  ): MonitorStep {
+    this.data!.networkDeviceMonitor = networkDeviceMonitor;
+    return this;
+  }
+
   public setSnmpMonitor(snmpMonitor: MonitorStepSnmpMonitor): MonitorStep {
     this.data!.snmpMonitor = snmpMonitor;
     return this;
@@ -681,20 +700,17 @@ export default class MonitorStep extends DatabaseProperty {
       return "Port is required";
     }
 
-    if (monitorType === MonitorType.SNMP) {
-      if (!value.data.snmpMonitor) {
-        return "SNMP configuration is required";
-      }
-
-      if (!value.data.snmpMonitor.hostname) {
-        return "SNMP hostname is required";
+    if (monitorType === MonitorType.NetworkDevice) {
+      if (!value.data.networkDeviceMonitor?.networkDeviceId) {
+        return "Network Device is required";
       }
 
       if (
-        !value.data.snmpMonitor.oids ||
-        value.data.snmpMonitor.oids.length === 0
+        !value.data.networkDeviceMonitor.monitorInterfaces &&
+        (!value.data.networkDeviceMonitor.oids ||
+          value.data.networkDeviceMonitor.oids.length === 0)
       ) {
-        return "At least one OID is required";
+        return "Enable interface monitoring or configure at least one OID";
       }
     }
 
@@ -886,6 +902,11 @@ export default class MonitorStep extends DatabaseProperty {
           snmpMonitor: this.data.snmpMonitor
             ? MonitorStepSnmpMonitorUtil.toJSON(this.data.snmpMonitor)
             : undefined,
+          networkDeviceMonitor: this.data.networkDeviceMonitor
+            ? MonitorStepNetworkDeviceMonitorUtil.toJSON(
+                this.data.networkDeviceMonitor,
+              )
+            : undefined,
           dnsMonitor: this.data.dnsMonitor
             ? MonitorStepDnsMonitorUtil.toJSON(this.data.dnsMonitor)
             : undefined,
@@ -1048,6 +1069,9 @@ export default class MonitorStep extends DatabaseProperty {
       snmpMonitor: json["snmpMonitor"]
         ? (json["snmpMonitor"] as JSONObject)
         : undefined,
+      networkDeviceMonitor: json["networkDeviceMonitor"]
+        ? (json["networkDeviceMonitor"] as JSONObject)
+        : undefined,
       dnsMonitor: json["dnsMonitor"]
         ? (json["dnsMonitor"] as JSONObject)
         : undefined,
@@ -1116,6 +1140,7 @@ export default class MonitorStep extends DatabaseProperty {
         metricMonitor: Zod.any().optional(),
         profileMonitor: Zod.any().optional(),
         snmpMonitor: Zod.any().optional(),
+        networkDeviceMonitor: Zod.any().optional(),
         dnsMonitor: Zod.any().optional(),
         domainMonitor: Zod.any().optional(),
         dnssecMonitor: Zod.any().optional(),

package/Types/Monitor/MonitorStepNetworkDeviceMonitor.ts

@@ -0,0 +1,55 @@
+import { JSONObject } from "../JSON";
+import SnmpOid from "./SnmpMonitor/SnmpOid";
+
+/*
+ * Step configuration for Network Device monitors. Unlike the retired SNMP
+ * monitor type, the step carries no connection details — it references a
+ * NetworkDevice resource which owns the hostname, credentials, and
+ * interface inventory. The server hydrates the device's SNMP config into
+ * the step (as `snmpMonitor`) when handing work to probes.
+ */
+export default interface MonitorStepNetworkDeviceMonitor {
+  networkDeviceId: string | undefined;
+  monitorInterfaces: boolean;
+  oids: Array<SnmpOid>;
+}
+
+export class MonitorStepNetworkDeviceMonitorUtil {
+  public static getDefault(): MonitorStepNetworkDeviceMonitor {
+    return {
+      networkDeviceId: undefined,
+      monitorInterfaces: true,
+      oids: [],
+    };
+  }
+
+  public static fromJSON(json: JSONObject): MonitorStepNetworkDeviceMonitor {
+    return {
+      networkDeviceId: (json["networkDeviceId"] as string) || undefined,
+      monitorInterfaces: json["monitorInterfaces"] !== false,
+      oids: ((json["oids"] as Array<JSONObject>) || []).map(
+        (oid: JSONObject) => {
+          return {
+            oid: (oid["oid"] as string) || "",
+            name: (oid["name"] as string) || undefined,
+            description: (oid["description"] as string) || undefined,
+          };
+        },
+      ),
+    };
+  }
+
+  public static toJSON(monitor: MonitorStepNetworkDeviceMonitor): JSONObject {
+    return {
+      networkDeviceId: monitor.networkDeviceId,
+      monitorInterfaces: monitor.monitorInterfaces,
+      oids: monitor.oids.map((oid: SnmpOid) => {
+        return {
+          oid: oid.oid,
+          name: oid.name,
+          description: oid.description,
+        };
+      }),
+    };
+  }
+}

package/Types/Monitor/MonitorStepSnmpMonitor.ts

@@ -15,6 +15,11 @@ export default interface MonitorStepSnmpMonitor {
   oids: Array<SnmpOid>;
   timeout: number;
   retries: number;
+  /*
+   * When true, the probe walks the IF-MIB interface tables on every check
+   * and reports per-interface status, bandwidth, and error metrics.
+   */
+  monitorInterfaces?: boolean | undefined;
 }
 
 export class MonitorStepSnmpMonitorUtil {
@@ -27,6 +32,7 @@ export class MonitorStepSnmpMonitorUtil {
       oids: [],
       timeout: 5000,
       retries: 3,
+      monitorInterfaces: false,
     };
   }
 
@@ -46,6 +52,7 @@ export class MonitorStepSnmpMonitorUtil {
       ),
       timeout: (json["timeout"] as number) || 5000,
       retries: (json["retries"] as number) || 3,
+      monitorInterfaces: Boolean(json["monitorInterfaces"]),
     };
   }
 
@@ -97,6 +104,7 @@ export class MonitorStepSnmpMonitorUtil {
       }),
       timeout: monitor.timeout,
       retries: monitor.retries,
+      monitorInterfaces: monitor.monitorInterfaces,
     };
   }
 }

package/Types/Monitor/MonitorType.ts

@@ -32,8 +32,13 @@ enum MonitorType {
   Exceptions = "Exceptions",
   Profiles = "Profiles",
 
-  // Network device monitoring
-  SNMP = "SNMP",
+  /*
+   * Network device monitoring (SNMP-based). Replaced the retired SNMP
+   * monitor type: instead of inline SNMP config, the monitor references a
+   * NetworkDevice resource that owns the credentials and interface
+   * inventory.
+   */
+  NetworkDevice = "Network Device",
 
   // DNS monitoring
   DNS = "DNS",
@@ -95,7 +100,7 @@ export class MonitorTypeHelper {
       },
       {
         label: "Network",
-        monitorTypes: [MonitorType.SNMP],
+        monitorTypes: [MonitorType.NetworkDevice],
       },
       {
         label: "Infrastructure",
@@ -332,10 +337,10 @@ export class MonitorTypeHelper {
         icon: IconProp.Fire,
       },
       {
-        monitorType: MonitorType.SNMP,
-        title: "SNMP",
+        monitorType: MonitorType.NetworkDevice,
+        title: "Network Device",
         description:
-          "This monitor type lets you monitor network devices like switches, routers, and firewalls via SNMP.",
+          "This monitor type lets you monitor a registered Network Device (switch, router, firewall, or access point) via SNMP — availability, interface status, bandwidth, and traps.",
         icon: IconProp.Signal,
       },
       {
@@ -411,7 +416,7 @@ export class MonitorTypeHelper {
       monitorType === MonitorType.SSLCertificate ||
       monitorType === MonitorType.SyntheticMonitor ||
       monitorType === MonitorType.CustomJavaScriptCode ||
-      monitorType === MonitorType.SNMP ||
+      monitorType === MonitorType.NetworkDevice ||
       monitorType === MonitorType.DNS ||
       monitorType === MonitorType.DNSSEC ||
       monitorType === MonitorType.Domain ||
@@ -437,7 +442,7 @@ export class MonitorTypeHelper {
       MonitorType.Traces,
       MonitorType.Exceptions,
       MonitorType.Profiles,
-      MonitorType.SNMP,
+      MonitorType.NetworkDevice,
       MonitorType.DNS,
       MonitorType.DNSSEC,
       MonitorType.Domain,
@@ -482,7 +487,7 @@ export class MonitorTypeHelper {
       monitorType === MonitorType.SSLCertificate ||
       monitorType === MonitorType.SyntheticMonitor ||
       monitorType === MonitorType.CustomJavaScriptCode ||
-      monitorType === MonitorType.SNMP ||
+      monitorType === MonitorType.NetworkDevice ||
       monitorType === MonitorType.DNS ||
       monitorType === MonitorType.DNSSEC ||
       monitorType === MonitorType.Domain ||

package/Types/Monitor/SnmpMonitor/LldpNeighbor.ts

@@ -0,0 +1,12 @@
+/*
+ * One neighbor entry from a device's LLDP remote table (LLDP-MIB
+ * lldpRemTable). Captured by the probe alongside the interface walk; the
+ * server matches remoteSysName / remoteChassisId against known
+ * NetworkDevices to build the topology graph.
+ */
+export default interface LldpNeighbor {
+  localInterfaceIndex?: number | undefined;
+  remoteChassisId?: string | undefined;
+  remotePortId?: string | undefined;
+  remoteSysName?: string | undefined;
+}

package/Types/Monitor/SnmpMonitor/NetworkDeviceAlertPack.ts

@@ -0,0 +1,116 @@
+import ObjectID from "../../ObjectID";
+import FilterCondition from "../../Filter/FilterCondition";
+import { CheckOn, CriteriaFilter, FilterType } from "../CriteriaFilter";
+import MonitorCriteriaInstance from "../MonitorCriteriaInstance";
+
+/*
+ * Prebuilt criteria for Network Device monitors — the alerts most operators
+ * want and would otherwise hand-build every time. Applying a pack appends
+ * these criteria instances to the monitor; the user still picks severities
+ * and on-call policies afterwards.
+ */
+export interface NetworkDeviceAlertPackItem {
+  name: string;
+  description: string;
+  filters: Array<CriteriaFilter>;
+  createIncidents: boolean;
+  createAlerts: boolean;
+}
+
+export interface NetworkDeviceAlertPackContext {
+  // Status to move the monitor to when a pack criteria matches (offline/degraded).
+  downMonitorStatusId?: ObjectID | undefined;
+}
+
+const PACK: Array<NetworkDeviceAlertPackItem> = [
+  {
+    name: "Device unreachable",
+    description:
+      "The device stopped answering SNMP — likely down or unreachable.",
+    filters: [
+      {
+        checkOn: CheckOn.SnmpIsOnline,
+        filterType: FilterType.False,
+        value: undefined,
+      },
+    ],
+    createIncidents: true,
+    createAlerts: false,
+  },
+  {
+    name: "Interface down",
+    description:
+      "An administratively-enabled interface went operationally down.",
+    filters: [
+      {
+        checkOn: CheckOn.SnmpInterfaceIsDown,
+        filterType: FilterType.True,
+        value: undefined,
+      },
+    ],
+    createIncidents: true,
+    createAlerts: false,
+  },
+  {
+    name: "Interface saturated",
+    description:
+      "An interface is running above 80% utilization — the link may need an upgrade.",
+    filters: [
+      {
+        checkOn: CheckOn.SnmpInterfaceUtilizationPercent,
+        filterType: FilterType.GreaterThan,
+        value: 80,
+      },
+    ],
+    createIncidents: false,
+    createAlerts: true,
+  },
+  {
+    name: "Interface errors",
+    description:
+      "An interface is logging errors — usually cabling, optics, or duplex problems.",
+    filters: [
+      {
+        checkOn: CheckOn.SnmpInterfaceErrorsPerSecond,
+        filterType: FilterType.GreaterThan,
+        value: 1,
+      },
+    ],
+    createIncidents: false,
+    createAlerts: true,
+  },
+];
+
+export default class NetworkDeviceAlertPackUtil {
+  public static getPackItems(): Array<NetworkDeviceAlertPackItem> {
+    return PACK;
+  }
+
+  /*
+   * Builds ready-to-append MonitorCriteriaInstances from the pack. Each is
+   * enabled and set to change monitor status; severities and on-call
+   * policies are left for the user to fill in.
+   */
+  public static buildCriteriaInstances(
+    context?: NetworkDeviceAlertPackContext,
+  ): Array<MonitorCriteriaInstance> {
+    return PACK.map((item: NetworkDeviceAlertPackItem) => {
+      const instance: MonitorCriteriaInstance = new MonitorCriteriaInstance();
+      instance.data = {
+        id: ObjectID.generate().toString(),
+        monitorStatusId: context?.downMonitorStatusId,
+        filterCondition: FilterCondition.All,
+        filters: item.filters,
+        incidents: [],
+        alerts: [],
+        createAlerts: item.createAlerts,
+        createIncidents: item.createIncidents,
+        changeMonitorStatus: item.createIncidents,
+        isEnabled: true,
+        name: item.name,
+        description: item.description,
+      };
+      return instance;
+    });
+  }
+}

package/Types/Monitor/SnmpMonitor/NetworkTopology.ts

@@ -0,0 +1,29 @@
+/*
+ * A derived view of the network topology for one project, built server-side
+ * from the LLDP neighbor data each device reports. Nodes are devices;
+ * unmanaged neighbors (LLDP peers with no matching NetworkDevice) appear as
+ * lightweight nodes so the graph doesn't dead-end. Edges are LLDP links.
+ */
+export type NetworkTopologyNodeStatus = "up" | "down" | "unknown";
+
+export interface NetworkTopologyNode {
+  // Device id for managed nodes; a synthetic "unmanaged:<key>" id otherwise.
+  id: string;
+  name: string;
+  isManaged: boolean;
+  status: NetworkTopologyNodeStatus;
+  interfacesUp?: number | undefined;
+  interfacesDown?: number | undefined;
+}
+
+export interface NetworkTopologyEdge {
+  fromNodeId: string;
+  toNodeId: string;
+  fromPort?: string | undefined;
+  toPort?: string | undefined;
+}
+
+export default interface NetworkTopology {
+  nodes: Array<NetworkTopologyNode>;
+  edges: Array<NetworkTopologyEdge>;
+}

package/Types/Monitor/SnmpMonitor/SnmpInterface.ts

@@ -0,0 +1,31 @@
+/*
+ * One row of the IF-MIB interface tables (ifTable + ifXTable), walked by the
+ * probe when interface monitoring is enabled on an SNMP monitor.
+ *
+ * Octet/error/discard counters are cumulative since device boot (64-bit HC
+ * counters preferred, 32-bit fallback). The `*PerSecond` and
+ * `utilizationPercent` fields are NOT collected from the device — the server
+ * computes them from the delta against the previous check before the
+ * response is persisted, so they are absent on the first check after a
+ * monitor is created and after a counter wrap or device reboot.
+ */
+export default interface SnmpInterface {
+  interfaceIndex: number;
+  name: string;
+  alias?: string | undefined;
+  isOperationallyUp: boolean;
+  isAdministrativelyUp: boolean;
+  speedInBitsPerSecond?: number | undefined;
+  inOctets?: number | undefined;
+  outOctets?: number | undefined;
+  inErrors?: number | undefined;
+  outErrors?: number | undefined;
+  inDiscards?: number | undefined;
+  outDiscards?: number | undefined;
+
+  // Computed server-side from the previous check. See note above.
+  inBitsPerSecond?: number | undefined;
+  outBitsPerSecond?: number | undefined;
+  utilizationPercent?: number | undefined;
+  errorsPerSecond?: number | undefined;
+}

package/Types/Monitor/SnmpMonitor/SnmpMonitorResponse.ts

@@ -1,5 +1,7 @@
 import ProbeAttempt from "../../Probe/ProbeAttempt";
 import SnmpDataType from "./SnmpDataType";
+import SnmpInterface from "./SnmpInterface";
+import LldpNeighbor from "./LldpNeighbor";
 
 export interface SnmpOidResponse {
   oid: string;
@@ -16,4 +18,26 @@ export default interface SnmpMonitorResponse {
   isTimeout?: boolean | undefined;
   probeAttempts?: Array<ProbeAttempt> | undefined;
   totalAttempts?: number | undefined;
+  /*
+   * Populated when interface monitoring is enabled on the monitor step.
+   * Undefined on older probes and when the interface walk failed (the
+   * failure is recorded in interfaceWalkFailure).
+   */
+  interfaces?: Array<SnmpInterface> | undefined;
+  interfaceWalkFailure?: string | undefined;
+  /*
+   * System-group identity (sysDescr / sysName), collected alongside the
+   * interface walk. Used to enrich the NetworkDevice resource.
+   */
+  systemInfo?:
+    | {
+        sysDescr?: string | undefined;
+        sysName?: string | undefined;
+      }
+    | undefined;
+  /*
+   * LLDP neighbors discovered during the walk (when interface monitoring is
+   * enabled). Used to build the network topology graph.
+   */
+  lldpNeighbors?: Array<LldpNeighbor> | undefined;
 }

package/Types/Monitor/SnmpMonitor/SnmpTrap.ts

@@ -0,0 +1,20 @@
+export interface SnmpTrapVarbind {
+  oid: string;
+  value: string;
+}
+
+/*
+ * An SNMP trap (or inform) received by a probe's trap receiver and forwarded
+ * to the server. For v1 traps the trapOid is derived from the standard
+ * generic-trap mapping (e.g. linkDown → 1.3.6.1.6.3.1.1.5.3) or
+ * enterprise.0.specific for enterprise traps; for v2c/v3 it is the value of
+ * the snmpTrapOID.0 varbind.
+ */
+export default interface SnmpTrap {
+  sourceIpAddress: string;
+  trapOid: string;
+  snmpVersion: string;
+  community?: string | undefined;
+  receivedAt: Date;
+  varbinds: Array<SnmpTrapVarbind>;
+}