@oneuptime/common 11.4.0 → 11.5.0

package/Utils/Dashboard/Components/DashboardLogChartComponent.ts

@@ -0,0 +1,99 @@
+import DashboardLogChartComponent from "../../../Types/Dashboard/DashboardComponents/DashboardLogChartComponent";
+import { ObjectType } from "../../../Types/JSON";
+import ObjectID from "../../../Types/ObjectID";
+import LogSeverity from "../../../Types/Log/LogSeverity";
+import DashboardBaseComponentUtil from "./DashboardBaseComponent";
+import {
+  ComponentArgument,
+  ComponentArgumentSection,
+  ComponentInputType,
+} from "../../../Types/Dashboard/DashboardComponents/ComponentArgument";
+import DashboardComponentType from "../../../Types/Dashboard/DashboardComponentType";
+import DashboardChartType from "../../../Types/Dashboard/Chart/ChartType";
+
+const DisplaySection: ComponentArgumentSection = {
+  name: "Display Options",
+  description: "Configure the chart heading and visualization",
+  order: 1,
+};
+
+const FiltersSection: ComponentArgumentSection = {
+  name: "Log Query",
+  description: "Choose which logs contribute to the chart",
+  order: 2,
+};
+
+export default class DashboardLogChartComponentUtil extends DashboardBaseComponentUtil {
+  public static override getDefaultComponent(): DashboardLogChartComponent {
+    return {
+      _type: ObjectType.DashboardComponent,
+      componentType: DashboardComponentType.LogChart,
+      widthInDashboardUnits: 8,
+      heightInDashboardUnits: 5,
+      topInDashboardUnits: 0,
+      leftInDashboardUnits: 0,
+      componentId: ObjectID.generate(),
+      minHeightInDashboardUnits: 3,
+      minWidthInDashboardUnits: 6,
+      arguments: {
+        chartType: DashboardChartType.Bar,
+      },
+    };
+  }
+
+  public static override getComponentConfigArguments(): Array<
+    ComponentArgument<DashboardLogChartComponent>
+  > {
+    return [
+      {
+        name: "Title",
+        description: "Header shown above the log-volume chart",
+        required: false,
+        type: ComponentInputType.Text,
+        id: "title",
+        placeholder: "Log Volume",
+        section: DisplaySection,
+      },
+      {
+        name: "Chart Type",
+        description: "How log volume is visualized over time",
+        required: true,
+        type: ComponentInputType.Dropdown,
+        id: "chartType",
+        section: DisplaySection,
+        dropdownOptions: [
+          { label: "Bar Chart", value: DashboardChartType.Bar },
+          { label: "Line Chart", value: DashboardChartType.Line },
+          { label: "Area Chart", value: DashboardChartType.Area },
+        ],
+      },
+      {
+        name: "Severities",
+        description: "Only count logs at the selected severity levels",
+        required: false,
+        type: ComponentInputType.MultiSelectDropdown,
+        id: "severityFilters",
+        placeholder: "All severities",
+        section: FiltersSection,
+        dropdownOptions: [
+          { label: "Fatal", value: LogSeverity.Fatal },
+          { label: "Error", value: LogSeverity.Error },
+          { label: "Warning", value: LogSeverity.Warning },
+          { label: "Information", value: LogSeverity.Information },
+          { label: "Debug", value: LogSeverity.Debug },
+          { label: "Trace", value: LogSeverity.Trace },
+          { label: "Unspecified", value: LogSeverity.Unspecified },
+        ],
+      },
+      {
+        name: "Body Contains",
+        description: "Only count logs whose body contains this text",
+        required: false,
+        type: ComponentInputType.Text,
+        id: "bodyContains",
+        placeholder: "Search text...",
+        section: FiltersSection,
+      },
+    ];
+  }
+}

package/Utils/Dashboard/Components/Index.ts

@@ -23,6 +23,7 @@ import DashboardKubernetesNodeListComponentUtil from "./DashboardKubernetesNodeL
 import DashboardKubernetesPodListComponentUtil from "./DashboardKubernetesPodListComponent";
 import DashboardKubernetesStatefulSetListComponentUtil from "./DashboardKubernetesStatefulSetListComponent";
 import DashboardLogStreamComponentUtil from "./DashboardLogStreamComponent";
+import DashboardLogChartComponentUtil from "./DashboardLogChartComponent";
 import DashboardMonitorListComponentUtil from "./DashboardMonitorListComponent";
 import DashboardPodmanContainerListComponentUtil from "./DashboardPodmanContainerListComponent";
 import DashboardPodmanHostListComponentUtil from "./DashboardPodmanHostListComponent";
@@ -80,6 +81,12 @@ export default class DashboardComponentsUtil {
       >;
     }
 
+    if (dashboardComponentType === DashboardComponentType.LogChart) {
+      return DashboardLogChartComponentUtil.getComponentConfigArguments() as Array<
+        ComponentArgument<DashboardBaseComponent>
+      >;
+    }
+
     if (dashboardComponentType === DashboardComponentType.TraceList) {
       return DashboardTraceListComponentUtil.getComponentConfigArguments() as Array<
         ComponentArgument<DashboardBaseComponent>

package/Utils/Monitor/LatencyMatrixUtil.ts

@@ -0,0 +1,162 @@
+import LatencyMatrix, {
+  LatencyMatrixAxisItem,
+  LatencyMatrixCell,
+} from "../../Types/Monitor/LatencyMatrix";
+import { JSONObject } from "../../Types/JSON";
+
+export interface LatencyMatrixMonitorInput {
+  id: string;
+  name: string;
+}
+
+export interface LatencyMatrixProbeInput {
+  id: string;
+  name: string;
+}
+
+export interface LatencyMatrixProbeResult {
+  monitorId: string;
+  probeId: string;
+  /*
+   * MonitorProbe.lastMonitoringLog: a map of monitorStepId -> the last
+   * ProbeMonitorResponse for that step. The matrix uses the most recently
+   * monitored step's response time and online state.
+   */
+  lastMonitoringLog?: JSONObject | undefined;
+}
+
+export default class LatencyMatrixUtil {
+  /*
+   * Shapes probe/monitor axes plus each monitor-probe pair's last-check
+   * snapshot into a dense grid. Pure over its inputs so it's unit-testable
+   * without a database.
+   */
+  public static buildMatrix(data: {
+    monitors: Array<LatencyMatrixMonitorInput>;
+    probes: Array<LatencyMatrixProbeInput>;
+    results: Array<LatencyMatrixProbeResult>;
+    now: Date;
+  }): LatencyMatrix {
+    const monitors: Array<LatencyMatrixAxisItem> = data.monitors.map(
+      (monitor: LatencyMatrixMonitorInput) => {
+        return { id: monitor.id, name: monitor.name };
+      },
+    );
+    const probes: Array<LatencyMatrixAxisItem> = data.probes.map(
+      (probe: LatencyMatrixProbeInput) => {
+        return { id: probe.id, name: probe.name };
+      },
+    );
+
+    const cells: Record<string, Record<string, LatencyMatrixCell>> = {};
+
+    // Seed every cell as "no data" so the grid is dense.
+    for (const monitor of monitors) {
+      cells[monitor.id] = {};
+      for (const probe of probes) {
+        cells[monitor.id]![probe.id] = {
+          monitorId: monitor.id,
+          probeId: probe.id,
+          hasData: false,
+        };
+      }
+    }
+
+    for (const result of data.results) {
+      const row: Record<string, LatencyMatrixCell> | undefined =
+        cells[result.monitorId];
+      if (!row || !row[result.probeId]) {
+        continue;
+      }
+
+      const latest: {
+        latencyInMs?: number | undefined;
+        isOnline?: boolean | undefined;
+        monitoredAt?: Date | undefined;
+      } | null = LatencyMatrixUtil.extractLatest(result.lastMonitoringLog);
+
+      if (!latest) {
+        continue;
+      }
+
+      const cell: LatencyMatrixCell = {
+        monitorId: result.monitorId,
+        probeId: result.probeId,
+        hasData: true,
+        latencyInMs: latest.latencyInMs,
+        isOnline: latest.isOnline,
+      };
+
+      if (latest.monitoredAt) {
+        cell.ageInSeconds = Math.max(
+          0,
+          Math.round(
+            (data.now.getTime() - new Date(latest.monitoredAt).getTime()) /
+              1000,
+          ),
+        );
+      }
+
+      row[result.probeId] = cell;
+    }
+
+    return { monitors, probes, cells };
+  }
+
+  /*
+   * Picks the most-recently-monitored step from a lastMonitoringLog and
+   * returns its latency / online / timestamp. Returns null when the log is
+   * empty or malformed.
+   */
+  private static extractLatest(log: JSONObject | undefined): {
+    latencyInMs?: number | undefined;
+    isOnline?: boolean | undefined;
+    monitoredAt?: Date | undefined;
+  } | null {
+    if (!log || typeof log !== "object") {
+      return null;
+    }
+
+    let best: {
+      latencyInMs?: number | undefined;
+      isOnline?: boolean | undefined;
+      monitoredAt?: Date | undefined;
+    } | null = null;
+    let bestTime: number = -Infinity;
+
+    for (const stepId of Object.keys(log)) {
+      const response: JSONObject | undefined = log[stepId] as
+        | JSONObject
+        | undefined;
+      if (!response || typeof response !== "object") {
+        continue;
+      }
+
+      const monitoredAtValue: unknown = response["monitoredAt"];
+      const monitoredAt: Date | undefined = monitoredAtValue
+        ? new Date(monitoredAtValue as string)
+        : undefined;
+      const time: number =
+        monitoredAt && !isNaN(monitoredAt.getTime())
+          ? monitoredAt.getTime()
+          : 0;
+
+      if (time >= bestTime) {
+        bestTime = time;
+        const latencyValue: unknown = response["responseTimeInMs"];
+        const onlineValue: unknown = response["isOnline"];
+        best = {
+          latencyInMs:
+            typeof latencyValue === "number" ? latencyValue : undefined,
+          isOnline: typeof onlineValue === "boolean" ? onlineValue : undefined,
+          monitoredAt:
+            monitoredAt && !isNaN(monitoredAt.getTime())
+              ? monitoredAt
+              : undefined,
+        };
+      }
+    }
+
+    return best;
+  }
+}

package/Utils/Monitor/MonitorMetricType.ts

@@ -33,6 +33,24 @@ class MonitorMetricTypeUtil {
         return AggregationType.Avg;
       case MonitorMetricType.ExecutionTime:
         return AggregationType.Avg;
+      case MonitorMetricType.PacketLossPercent:
+        return AggregationType.Avg;
+      case MonitorMetricType.Jitter:
+        return AggregationType.Avg;
+      case MonitorMetricType.DnsLookupTime:
+      case MonitorMetricType.TcpConnectTime:
+      case MonitorMetricType.TlsHandshakeTime:
+      case MonitorMetricType.TimeToFirstByte:
+      case MonitorMetricType.DownloadTime:
+        return AggregationType.Avg;
+      case MonitorMetricType.SnmpInterfaceOperStatus:
+        return AggregationType.Min;
+      case MonitorMetricType.SnmpInterfaceInBitsPerSecond:
+      case MonitorMetricType.SnmpInterfaceOutBitsPerSecond:
+      case MonitorMetricType.SnmpInterfaceErrorsPerSecond:
+        return AggregationType.Avg;
+      case MonitorMetricType.SnmpInterfaceUtilizationPercent:
+        return AggregationType.Max;
 
       /*
        * Extended server/VM metrics. Cumulative counters (bytes/packets/ops since
@@ -79,6 +97,10 @@ class MonitorMetricTypeUtil {
     switch (checkOn) {
       case CheckOn.ResponseTime:
         return MonitorMetricType.ResponseTime;
+      case CheckOn.PacketLossPercent:
+        return MonitorMetricType.PacketLossPercent;
+      case CheckOn.Jitter:
+        return MonitorMetricType.Jitter;
       case CheckOn.ResponseStatusCode:
         return MonitorMetricType.ResponseStatusCode;
       case CheckOn.IsOnline:
@@ -117,6 +139,11 @@ class MonitorMetricTypeUtil {
         MonitorMetricType.IsOnline,
         MonitorMetricType.ResponseTime,
         MonitorMetricType.ResponseStatusCode,
+        MonitorMetricType.DnsLookupTime,
+        MonitorMetricType.TcpConnectTime,
+        MonitorMetricType.TlsHandshakeTime,
+        MonitorMetricType.TimeToFirstByte,
+        MonitorMetricType.DownloadTime,
       ];
     }
 
@@ -165,11 +192,33 @@ class MonitorMetricTypeUtil {
       return [MonitorMetricType.ExecutionTime];
     }
 
+    if (monitorType === MonitorType.Ping || monitorType === MonitorType.IP) {
+      /*
+       * Ping/IP checks send multiple echo requests, so they get packet-level
+       * network metrics on top of availability and response time.
+       */
+      return [
+        MonitorMetricType.IsOnline,
+        MonitorMetricType.ResponseTime,
+        MonitorMetricType.PacketLossPercent,
+        MonitorMetricType.Jitter,
+      ];
+    }
+
+    if (monitorType === MonitorType.NetworkDevice) {
+      return [
+        MonitorMetricType.IsOnline,
+        MonitorMetricType.ResponseTime,
+        MonitorMetricType.SnmpInterfaceOperStatus,
+        MonitorMetricType.SnmpInterfaceInBitsPerSecond,
+        MonitorMetricType.SnmpInterfaceOutBitsPerSecond,
+        MonitorMetricType.SnmpInterfaceUtilizationPercent,
+        MonitorMetricType.SnmpInterfaceErrorsPerSecond,
+      ];
+    }
+
     if (
-      monitorType === MonitorType.Ping ||
-      monitorType === MonitorType.IP ||
       monitorType === MonitorType.Port ||
-      monitorType === MonitorType.SNMP ||
       monitorType === MonitorType.DNS ||
       monitorType === MonitorType.DNSSEC ||
       monitorType === MonitorType.Domain ||
@@ -255,6 +304,28 @@ class MonitorMetricTypeUtil {
       ];
     }
 
+    if (monitorType === MonitorType.NetworkDevice) {
+      return [
+        {
+          title: "Availability",
+          description: "Device reachability and SNMP response time.",
+          metrics: [MonitorMetricType.IsOnline, MonitorMetricType.ResponseTime],
+        },
+        {
+          title: "Interfaces",
+          description:
+            "Per-interface status, bandwidth, utilization, and errors. One series per interface.",
+          metrics: [
+            MonitorMetricType.SnmpInterfaceOperStatus,
+            MonitorMetricType.SnmpInterfaceInBitsPerSecond,
+            MonitorMetricType.SnmpInterfaceOutBitsPerSecond,
+            MonitorMetricType.SnmpInterfaceUtilizationPercent,
+            MonitorMetricType.SnmpInterfaceErrorsPerSecond,
+          ],
+        },
+      ];
+    }
+
     // Other monitor types keep the single-card layout.
     const metrics: Array<MonitorMetricType> =
       this.getMonitorMetricTypesByMonitorType(monitorType);
@@ -288,6 +359,30 @@ class MonitorMetricTypeUtil {
         return "Memory Usage Percent";
       case MonitorMetricType.ExecutionTime:
         return "Execution Time";
+      case MonitorMetricType.PacketLossPercent:
+        return "Packet Loss";
+      case MonitorMetricType.Jitter:
+        return "Jitter";
+      case MonitorMetricType.DnsLookupTime:
+        return "DNS Lookup Time";
+      case MonitorMetricType.TcpConnectTime:
+        return "TCP Connect Time";
+      case MonitorMetricType.TlsHandshakeTime:
+        return "TLS Handshake Time";
+      case MonitorMetricType.TimeToFirstByte:
+        return "Time to First Byte";
+      case MonitorMetricType.DownloadTime:
+        return "Download Time";
+      case MonitorMetricType.SnmpInterfaceOperStatus:
+        return "Interface Status";
+      case MonitorMetricType.SnmpInterfaceInBitsPerSecond:
+        return "Interface Inbound Bandwidth";
+      case MonitorMetricType.SnmpInterfaceOutBitsPerSecond:
+        return "Interface Outbound Bandwidth";
+      case MonitorMetricType.SnmpInterfaceUtilizationPercent:
+        return "Interface Utilization";
+      case MonitorMetricType.SnmpInterfaceErrorsPerSecond:
+        return "Interface Errors";
       case MonitorMetricType.LoadAverage1Min:
         return "Load Average (1 minute)";
       case MonitorMetricType.LoadAverage5Min:
@@ -370,6 +465,25 @@ class MonitorMetricTypeUtil {
         return "%";
       case MonitorMetricType.ExecutionTime:
         return "ms";
+      case MonitorMetricType.PacketLossPercent:
+        return "%";
+      case MonitorMetricType.Jitter:
+        return "ms";
+      case MonitorMetricType.DnsLookupTime:
+      case MonitorMetricType.TcpConnectTime:
+      case MonitorMetricType.TlsHandshakeTime:
+      case MonitorMetricType.TimeToFirstByte:
+      case MonitorMetricType.DownloadTime:
+        return "ms";
+      case MonitorMetricType.SnmpInterfaceOperStatus:
+        return "";
+      case MonitorMetricType.SnmpInterfaceInBitsPerSecond:
+      case MonitorMetricType.SnmpInterfaceOutBitsPerSecond:
+        return "bps";
+      case MonitorMetricType.SnmpInterfaceUtilizationPercent:
+        return "%";
+      case MonitorMetricType.SnmpInterfaceErrorsPerSecond:
+        return "errors/s";
       case MonitorMetricType.LoadAverage1Min:
       case MonitorMetricType.LoadAverage5Min:
       case MonitorMetricType.LoadAverage15Min:
@@ -426,6 +540,30 @@ class MonitorMetricTypeUtil {
         return "Memory usage percent is the percentage of memory that is currently being used on a server. It is a measure of how much of the server's memory is being used.";
       case MonitorMetricType.ExecutionTime:
         return "Execution time is the time taken for a custom JavaScript code or a synthetic monitor to execute.";
+      case MonitorMetricType.PacketLossPercent:
+        return "Percentage of ICMP echo requests that received no reply during this check. Sustained loss above 1-2% typically indicates congestion, faulty hardware, or routing problems on the path.";
+      case MonitorMetricType.Jitter:
+        return "Variation in round-trip time across the packets sent in each check (standard deviation). High jitter degrades real-time traffic like VoIP and video even when average latency looks healthy.";
+      case MonitorMetricType.DnsLookupTime:
+        return "Time spent resolving the hostname to an IP address. Spikes here point at the DNS provider, not the monitored service.";
+      case MonitorMetricType.TcpConnectTime:
+        return "Time spent establishing the TCP connection after DNS resolution — a proxy for raw network latency to the target.";
+      case MonitorMetricType.TlsHandshakeTime:
+        return "Time spent negotiating TLS after the TCP connection was established. Regressions here often follow certificate or cipher configuration changes.";
+      case MonitorMetricType.TimeToFirstByte:
+        return "Time from the end of connection setup until the first byte of the response arrived — the server-side processing time.";
+      case MonitorMetricType.DownloadTime:
+        return "Time spent receiving the response body after the first byte arrived.";
+      case MonitorMetricType.SnmpInterfaceOperStatus:
+        return "Operational status of each interface: 1 when up, 0 when down. Interfaces that are administratively disabled also report 0.";
+      case MonitorMetricType.SnmpInterfaceInBitsPerSecond:
+        return "Inbound traffic per interface, computed from the delta of IF-MIB octet counters between checks.";
+      case MonitorMetricType.SnmpInterfaceOutBitsPerSecond:
+        return "Outbound traffic per interface, computed from the delta of IF-MIB octet counters between checks.";
+      case MonitorMetricType.SnmpInterfaceUtilizationPercent:
+        return "Traffic in the busiest direction as a percentage of the interface's reported speed. Sustained values above 80% typically mean the link needs an upgrade.";
+      case MonitorMetricType.SnmpInterfaceErrorsPerSecond:
+        return "Combined inbound and outbound errors per second per interface. A non-zero rate usually points to cabling, SFP, or duplex problems.";
       case MonitorMetricType.LoadAverage1Min:
         return "Average number of runnable or uninterruptible processes over the last 1 minute. Values persistently above the number of CPU cores indicate CPU saturation.";
       case MonitorMetricType.LoadAverage5Min:

package/Utils/Monitor/NetworkTopologyUtil.ts

@@ -0,0 +1,159 @@
+import NetworkTopology, {
+  NetworkTopologyEdge,
+  NetworkTopologyNode,
+  NetworkTopologyNodeStatus,
+} from "../../Types/Monitor/SnmpMonitor/NetworkTopology";
+import LldpNeighbor from "../../Types/Monitor/SnmpMonitor/LldpNeighbor";
+
+export interface TopologyDeviceInput {
+  id: string;
+  name: string;
+  hostname?: string | undefined;
+  sysName?: string | undefined;
+  lastSeenAt?: Date | undefined;
+  interfacesUp?: number | undefined;
+  interfacesDown?: number | undefined;
+  lldpNeighbors?: Array<LldpNeighbor> | undefined;
+}
+
+// A device not seen within this window is treated as not currently up.
+const FRESH_WINDOW_MS: number = 15 * 60 * 1000;
+
+export default class NetworkTopologyUtil {
+  /*
+   * Builds the topology graph from every device in a project. Nodes are the
+   * devices; LLDP neighbors that match another device (by sysName or
+   * hostname) become edges, and neighbors that match nothing become
+   * lightweight "unmanaged" nodes so links don't dead-end. Edges are
+   * undirected and deduplicated, so a link reported from both ends appears
+   * once.
+   */
+  public static buildTopology(
+    devices: Array<TopologyDeviceInput>,
+    now: Date,
+  ): NetworkTopology {
+    const nodes: Array<NetworkTopologyNode> = [];
+    const edges: Array<NetworkTopologyEdge> = [];
+
+    // Index managed devices by the identifiers LLDP neighbors reference.
+    const deviceByMatchKey: Map<string, TopologyDeviceInput> = new Map();
+    for (const device of devices) {
+      for (const key of NetworkTopologyUtil.matchKeysForDevice(device)) {
+        deviceByMatchKey.set(key, device);
+      }
+    }
+
+    for (const device of devices) {
+      nodes.push({
+        id: device.id,
+        name: device.name,
+        isManaged: true,
+        status: NetworkTopologyUtil.deviceStatus(device, now),
+        interfacesUp: device.interfacesUp,
+        interfacesDown: device.interfacesDown,
+      });
+    }
+
+    const unmanagedNodeIds: Set<string> = new Set();
+    const seenEdgeKeys: Set<string> = new Set();
+
+    for (const device of devices) {
+      for (const neighbor of device.lldpNeighbors || []) {
+        const matchKey: string | undefined =
+          NetworkTopologyUtil.normalizeKey(neighbor.remoteSysName) ||
+          NetworkTopologyUtil.normalizeKey(neighbor.remoteChassisId);
+
+        if (!matchKey) {
+          continue;
+        }
+
+        const matched: TopologyDeviceInput | undefined =
+          deviceByMatchKey.get(matchKey);
+
+        let toNodeId: string;
+
+        if (matched) {
+          if (matched.id === device.id) {
+            // Self-referential neighbor entry; skip.
+            continue;
+          }
+          toNodeId = matched.id;
+        } else {
+          toNodeId = `unmanaged:${matchKey}`;
+          if (!unmanagedNodeIds.has(toNodeId)) {
+            unmanagedNodeIds.add(toNodeId);
+            nodes.push({
+              id: toNodeId,
+              name:
+                neighbor.remoteSysName ||
+                neighbor.remoteChassisId ||
+                "Unknown device",
+              isManaged: false,
+              status: "unknown",
+            });
+          }
+        }
+
+        // Undirected dedupe: canonicalize the endpoint pair.
+        const edgeKey: string = [device.id, toNodeId].sort().join("::");
+        if (seenEdgeKeys.has(edgeKey)) {
+          continue;
+        }
+        seenEdgeKeys.add(edgeKey);
+
+        edges.push({
+          fromNodeId: device.id,
+          toNodeId: toNodeId,
+          fromPort:
+            neighbor.localInterfaceIndex !== undefined
+              ? `if${neighbor.localInterfaceIndex}`
+              : undefined,
+          toPort: neighbor.remotePortId,
+        });
+      }
+    }
+
+    return { nodes, edges };
+  }
+
+  private static matchKeysForDevice(
+    device: TopologyDeviceInput,
+  ): Array<string> {
+    const keys: Array<string> = [];
+    const sysNameKey: string | undefined = NetworkTopologyUtil.normalizeKey(
+      device.sysName,
+    );
+    const hostnameKey: string | undefined = NetworkTopologyUtil.normalizeKey(
+      device.hostname,
+    );
+    if (sysNameKey) {
+      keys.push(sysNameKey);
+    }
+    if (hostnameKey) {
+      keys.push(hostnameKey);
+    }
+    return keys;
+  }
+
+  private static normalizeKey(value: string | undefined): string | undefined {
+    if (!value) {
+      return undefined;
+    }
+    const trimmed: string = value.trim().toLowerCase();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+
+  private static deviceStatus(
+    device: TopologyDeviceInput,
+    now: Date,
+  ): NetworkTopologyNodeStatus {
+    if (!device.lastSeenAt) {
+      return "unknown";
+    }
+    const ageMs: number = now.getTime() - new Date(device.lastSeenAt).getTime();
+    if (ageMs > FRESH_WINDOW_MS) {
+      return "down";
+    }
+    return "up";
+  }
+}

package/Utils/Telemetry/EntityRelationship.ts

@@ -11,11 +11,22 @@ import EntityType from "../../Types/Telemetry/EntityType";
  * synchronous: operates on already-computed entity keys, no DB round trip.
  */
 
+/**
+ * Traffic observed over a `depends-on` edge in one computation window.
+ * Co-occurrence edges carry no call semantics and never have these.
+ */
+export interface EntityRelationshipMetrics {
+  callCount: number;
+  errorCount: number;
+  avgDurationMs: number;
+}
+
 /** A single directed relationship edge between two entities. */
 export interface EntityRelationshipEdge {
   fromEntityKey: string;
   toEntityKey: string;
   relationshipType: EntityRelationshipType;
+  metrics?: EntityRelationshipMetrics | undefined;
 }
 
 /*