@oneuptime/common 12.0.34 → 13.0.0

package/Server/Utils/Monitor/MonitorCriteriaObservationBuilder.ts

@@ -41,6 +41,7 @@ import MetricQueryConfigData from "../../../Types/Metrics/MetricQueryConfigData"
 import MetricFormulaConfigData from "../../../Types/Metrics/MetricFormulaConfigData";
 import MetricsViewConfig from "../../../Types/Metrics/MetricsViewConfig";
 import MetricUnitUtil from "../../../Utils/MetricUnitUtil";
+import MetricValueFormatter from "../../../Utils/Monitor/MetricValueFormatter";
 
 export default class MonitorCriteriaObservationBuilder {
   public static describeFilterObservation(input: {
@@ -1220,18 +1221,33 @@ export default class MonitorCriteriaObservationBuilder {
      * that unit alongside the numbers so the message reads "latest 0.06 sec"
      * instead of the unitless "latest 0.06".
      */
-    const displayUnit: string | undefined =
-      MonitorCriteriaObservationBuilder.resolveMetricUnits({
-        criteriaFilter: input.criteriaFilter,
-        dataToProcess: input.dataToProcess,
-        monitorStep: input.monitorStep,
-        alias: metricValues.alias,
-      }).displayUnit;
+    const resolvedUnits: {
+      displayUnit: string | undefined;
+      metricName: string | undefined;
+    } = MonitorCriteriaObservationBuilder.resolveMetricUnits({
+      criteriaFilter: input.criteriaFilter,
+      dataToProcess: input.dataToProcess,
+      monitorStep: input.monitorStep,
+      alias: metricValues.alias,
+    });
 
+    /*
+     * The same renderer the fired-alert email uses. Before this, a breach
+     * that CompareCriteria wrote into the email as "1.07 GB" appeared in
+     * the monitor's own evaluation log as "1073741824.00 By" — one sample,
+     * two descriptions, on two screens a reader compares.
+     */
     const summary: string | null =
       MonitorCriteriaMessageFormatter.summarizeNumericSeries(
         displayValues,
-        displayUnit,
+        resolvedUnits.displayUnit,
+        (value: number): string => {
+          return MetricValueFormatter.format({
+            value: value,
+            unit: resolvedUnits.displayUnit,
+            metricName: resolvedUnits.metricName,
+          });
+        },
       );
 
     if (!summary) {
@@ -1304,6 +1320,18 @@ export default class MonitorCriteriaObservationBuilder {
     sampleUnit: string | undefined;
     thresholdUnit: string | undefined;
     displayUnit: string | undefined;
+    /**
+     * The metric NAME, for the two decisions MetricValueFormatter cannot
+     * make from a unit alone: whether a "1"-unit value is a fraction to
+     * render as a percent, and whether a "seconds"-unit value is really an
+     * epoch that must skip the duration ladder.
+     *
+     * Undefined for a formula. A formula's "name" is its expression, and an
+     * expression ending in `_ratio` would trip the fraction heuristic into
+     * reporting every value at 100x — the same guard
+     * MonitorCriteriaEvaluator.metricNameForUnitHeuristics applies.
+     */
+    metricName: string | undefined;
   } {
     const thresholdUnit: string | undefined =
       input.criteriaFilter.metricMonitorOptions?.thresholdUnit || undefined;
@@ -1317,6 +1345,7 @@ export default class MonitorCriteriaObservationBuilder {
         sampleUnit: undefined,
         thresholdUnit,
         displayUnit: thresholdUnit,
+        metricName: undefined,
       };
     }
 
@@ -1355,35 +1384,42 @@ export default class MonitorCriteriaObservationBuilder {
       nativeUnitFromMap ||
       undefined;
 
+    const displayUnit: string | undefined = thresholdUnit || sampleUnit;
+
     return {
       sampleUnit,
       thresholdUnit,
       displayUnit: MonitorCriteriaObservationBuilder.normalizeDisplayUnit(
-        thresholdUnit || sampleUnit,
+        displayUnit,
+        rawMetricName,
       ),
+      metricName: rawMetricName,
     };
   }
 
   /*
-   * Suppress units that would read as noise next to a raw number. OTel's
-   * dimensionless "1" marks ratio metrics whose samples are fractions in
-   * [0, 1]; rendering "0.06 1" is both ugly and misleading (it is not 1% —
-   * it is 6%). Returning undefined leaves the number unlabelled, matching
-   * the pre-unit behavior for that specific case. Any real unit passes
-   * through unchanged.
+   * Suppress units that name no dimension, so they never reach a reader
+   * next to a number.
+   *
+   * This used to be a hand-rolled rule that dropped only the literal "1",
+   * and it drifted from the one CompareCriteria applies to the very same
+   * sample: a ratio metric's evaluation log read a bare "latest 0.06"
+   * while the alert email for the identical value said "6.00%". It also
+   * let UCUM's "{restarts}" and the platform catalogs' "count" / "ratio"
+   * through, none of which mean anything to a reader.
+   *
+   * MetricValueFormatter owns that rule now. Note it is name-AWARE where
+   * the old one was not: "1" on a `.utilization` metric is a real
+   * dimension (a fraction to be shown as a percent), so it survives here
+   * and the formatter turns it into "%".
    */
   private static normalizeDisplayUnit(
     unit: string | undefined,
+    metricName?: string | undefined,
   ): string | undefined {
-    if (!unit || !unit.trim()) {
-      return undefined;
-    }
-
-    if (unit.trim() === "1") {
-      return undefined;
-    }
-
-    return unit;
+    return MetricValueFormatter.hasDisplayableUnit(unit, metricName)
+      ? unit
+      : undefined;
   }
 
   /*
@@ -1399,6 +1435,24 @@ export default class MonitorCriteriaObservationBuilder {
     dataToProcess: DataToProcess;
     monitorStep: MonitorStep;
   }): string | undefined {
+    return MonitorCriteriaObservationBuilder.getMetricValueDisplayContext(input)
+      .unit;
+  }
+
+  /**
+   * The unit AND the metric name a criteria's values are displayed in.
+   *
+   * The expectation clause needs both, not just the unit: it renders the
+   * threshold through the same MetricValueFormatter as the observation, and
+   * the formatter's fraction and epoch-timestamp rules are keyed on the
+   * name. Without it, "recorded latest 6.00%" would be followed by
+   * "(expected to be greater than 0.9)".
+   */
+  public static getMetricValueDisplayContext(input: {
+    criteriaFilter: CriteriaFilter;
+    dataToProcess: DataToProcess;
+    monitorStep: MonitorStep;
+  }): { unit: string | undefined; metricName: string | undefined } {
     /*
      * Database Health thresholds are typed in the metric's own unit, which
      * only the catalog knows - without this the expectation clause reads
@@ -1412,13 +1466,17 @@ export default class MonitorCriteriaObservationBuilder {
         ? getDatabaseMetricByMetricType(metricType)
         : null;
 
-      return MonitorCriteriaObservationBuilder.normalizeDisplayUnit(
-        definition?.unit,
-      );
+      return {
+        unit: MonitorCriteriaObservationBuilder.normalizeDisplayUnit(
+          definition?.unit,
+        ),
+        // Catalog units are explicit; no name-based heuristic is wanted.
+        metricName: undefined,
+      };
     }
 
     if (input.criteriaFilter.checkOn !== CheckOn.MetricValue) {
-      return undefined;
+      return { unit: undefined, metricName: undefined };
     }
 
     const metricValues: {
@@ -1430,12 +1488,17 @@ export default class MonitorCriteriaObservationBuilder {
       monitorStep: input.monitorStep,
     });
 
-    return MonitorCriteriaObservationBuilder.resolveMetricUnits({
+    const resolved: {
+      displayUnit: string | undefined;
+      metricName: string | undefined;
+    } = MonitorCriteriaObservationBuilder.resolveMetricUnits({
       criteriaFilter: input.criteriaFilter,
       dataToProcess: input.dataToProcess,
       monitorStep: input.monitorStep,
       alias: metricValues?.alias ?? null,
-    }).displayUnit;
+    });
+
+    return { unit: resolved.displayUnit, metricName: resolved.metricName };
   }
 
   private static getSnmpResponse(input: {
@@ -1743,28 +1806,24 @@ export default class MonitorCriteriaObservationBuilder {
     }
   }
 
+  /*
+   * A Database Health metric carries an explicit catalog unit, and
+   * DatabaseMonitorCriteria already hands that same unit to CompareCriteria
+   * for the fired-alert email. Rendering it here through anything else made
+   * one byte count read three ways in one product: the email said
+   * "1.07 GB" (decimal, via MetricValueFormatter), this observation said
+   * "1.00 GB" (formatBytes divides by 1024 but labels the rungs SI), and
+   * the expectation clause beside it said "1000000000 bytes".
+   *
+   * formatBytes stays for the server-monitor memory and disk observations,
+   * where the values come from BasicMetrics with no unit metadata at all
+   * and 1024 is the right convention for RAM and volumes.
+   */
   private static formatDatabaseMetricValue(
     value: number,
     unit: string,
   ): string {
-    if (unit === "%") {
-      return (
-        MonitorCriteriaMessageFormatter.formatPercentage(value) ?? String(value)
-      );
-    }
-
-    if (unit === "bytes") {
-      return (
-        MonitorCriteriaMessageFormatter.formatBytes(value) ?? String(value)
-      );
-    }
-
-    const formatted: string =
-      MonitorCriteriaMessageFormatter.formatNumber(value, {
-        maximumFractionDigits: 2,
-      }) ?? String(value);
-
-    return unit ? `${formatted} ${unit}` : formatted;
+    return MetricValueFormatter.format({ value: value, unit: unit });
   }
 
   private static describeDatabaseCollectionErrorObservation(input: {

package/Server/Utils/Monitor/NetworkDeviceMacLearningUtil.ts

@@ -0,0 +1,158 @@
+import NetworkDevice from "../../../Models/DatabaseModels/NetworkDevice";
+import NetworkDeviceService from "../../Services/NetworkDeviceService";
+import QueryHelper from "../../Types/Database/QueryHelper";
+import LIMIT_MAX from "../../../Types/Database/LimitMax";
+import ObjectID from "../../../Types/ObjectID";
+import DeviceMacLearningUtil, {
+  MacLearningCandidateDevice,
+  MacLearningIpBinding,
+  MacLearningPlanEntry,
+} from "../../../Utils/Monitor/DeviceMacLearningUtil";
+import logger from "../Logger";
+
+/*
+ * Fills NetworkDevice.macAddress from a walked router's ARP table.
+ *
+ * Runs once per successful walk that carried ARP entries, after the
+ * endpoint inventory has been written. The decision of WHICH devices to
+ * stamp is DeviceMacLearningUtil.planMacLearning (pure, tested without a
+ * database); this only fetches the candidates and applies the plan.
+ *
+ * The write is hook-free and compare-and-set: a row is stamped only while
+ * its MAC column still holds what the plan saw (NULL for a first learn, the
+ * previously learned MAC for a correction), so an operator who types a MAC
+ * between the read and the write keeps theirs, and two walks racing on one
+ * row cannot both land. A stable site plans nothing - every device already
+ * holds what the table says - so it costs one indexed read per walk and no
+ * writes, which is what keeps this affordable at fleet scale.
+ *
+ * The write cannot tell the caller whether the compare-and-set matched a
+ * row, so the result counts what was PLANNED, not what landed.
+ */
+
+// Same chunking NetworkDeviceService.getDevicesByHostnames uses.
+const HOSTNAME_LOOKUP_CHUNK_SIZE: number = 500;
+
+export interface MacLearningResult {
+  candidateDeviceCount: number;
+  // Writes issued. A compare-and-set that matched nothing is not subtracted.
+  plannedCount: number;
+}
+
+export default class NetworkDeviceMacLearningUtil {
+  public static async learnFromArpBindings(data: {
+    projectId: ObjectID;
+    // The router (or L3 switch) whose ARP table this is.
+    observingDeviceId: ObjectID;
+    observingSiteId: ObjectID | undefined;
+    ipBindings: Array<MacLearningIpBinding>;
+  }): Promise<MacLearningResult> {
+    const addresses: Array<string> = Array.from(
+      new Set<string>(
+        data.ipBindings
+          .map((binding: MacLearningIpBinding) => {
+            return (binding.ipAddress || "").trim();
+          })
+          .filter((ip: string) => {
+            return ip.length > 0;
+          }),
+      ),
+    );
+
+    if (addresses.length === 0) {
+      return { candidateDeviceCount: 0, plannedCount: 0 };
+    }
+
+    /*
+     * Every live device in the project registered at one of the bound
+     * addresses. Not filtered by site or by an empty MAC column in SQL:
+     * the planner needs to SEE a second device at the same address, or a
+     * device that already has a MAC, to refuse correctly - a query that
+     * hid them would make "exactly one" true by accident.
+     */
+    const candidates: Array<MacLearningCandidateDevice> = [];
+
+    for (
+      let offset: number = 0;
+      offset < addresses.length;
+      offset += HOSTNAME_LOOKUP_CHUNK_SIZE
+    ) {
+      const chunk: Array<string> = addresses.slice(
+        offset,
+        offset + HOSTNAME_LOOKUP_CHUNK_SIZE,
+      );
+
+      const devices: Array<NetworkDevice> = await NetworkDeviceService.findBy({
+        query: {
+          projectId: data.projectId,
+          hostname: QueryHelper.any(chunk),
+          isArchived: false,
+        },
+        select: {
+          _id: true,
+          hostname: true,
+          siteId: true,
+          macAddress: true,
+          isMacAddressLearned: true,
+        },
+        limit: LIMIT_MAX,
+        skip: 0,
+        props: {
+          isRoot: true,
+        },
+      });
+
+      for (const device of devices) {
+        if (!device.id) {
+          continue;
+        }
+        candidates.push({
+          id: device.id.toString(),
+          hostname: device.hostname,
+          siteId: device.siteId?.toString(),
+          macAddress: device.macAddress,
+          isMacAddressLearned: device.isMacAddressLearned,
+        });
+      }
+    }
+
+    const plan: Array<MacLearningPlanEntry> =
+      DeviceMacLearningUtil.planMacLearning({
+        ipBindings: data.ipBindings,
+        devices: candidates,
+        observingSiteId: data.observingSiteId?.toString(),
+      });
+
+    let plannedCount: number = 0;
+
+    for (const entry of plan) {
+      await NetworkDeviceService.updateColumnsByIdWithoutHooks({
+        id: new ObjectID(entry.deviceId),
+        data: {
+          macAddress: entry.macAddress,
+          isMacAddressLearned: true,
+        } as any,
+        /*
+         * Only while the column still holds what the plan saw - empty, or
+         * the learned value being corrected - and never a row that was
+         * deleted between the read and this write.
+         */
+        expectedData: {
+          macAddress: entry.previousMacAddress,
+          deletedAt: null,
+        } as any,
+      });
+      plannedCount++;
+
+      logger.debug(
+        `Planned MAC ${entry.macAddress} for network device ${entry.deviceId} (${entry.ipAddress}) from the ARP table of device ${data.observingDeviceId.toString()}${
+          entry.previousMacAddress
+            ? `, correcting the learned ${entry.previousMacAddress}`
+            : ""
+        }; skipped if the column changed meanwhile.`,
+      );
+    }
+
+    return { candidateDeviceCount: candidates.length, plannedCount };
+  }
+}

package/Server/Utils/Monitor/NetworkInventoryUtil.ts

@@ -1,6 +1,7 @@
 import NetworkDevice from "../../../Models/DatabaseModels/NetworkDevice";
 import NetworkDeviceService from "../../Services/NetworkDeviceService";
 import NetworkEndpointService from "../../Services/NetworkEndpointService";
+import NetworkDeviceMacLearningUtil from "./NetworkDeviceMacLearningUtil";
 import NetworkInterfaceService, {
   InterfaceWalkUpsertResult,
 } from "../../Services/NetworkInterfaceService";
@@ -445,6 +446,32 @@ export default class NetworkInventoryUtil {
             now: now,
           });
         }
+
+        /*
+         * --- Device MAC learning (ARP) ---
+         * The ARP table also names the MACs of managed devices registered
+         * at the addresses it binds - the ping-only registers and handsets
+         * that the switches' forwarding tables can put on a port, but only
+         * once something has said which MAC is theirs. Stamped on the
+         * device, once, while its MAC column is empty. Its own try/catch:
+         * the endpoint inventory above is already written, and a failure
+         * here must not read as one there.
+         */
+        if (endpointResult.ipBindings.length > 0) {
+          try {
+            await NetworkDeviceMacLearningUtil.learnFromArpBindings({
+              projectId: data.projectId,
+              observingDeviceId: deviceId,
+              observingSiteId: ownedDevice.siteId,
+              ipBindings: endpointResult.ipBindings,
+            });
+          } catch (err) {
+            logger.error(
+              `Failed to learn device MAC addresses from the ARP table of network device ${deviceId.toString()}:`,
+            );
+            logger.error(err);
+          }
+        }
       }
     } catch (err) {
       // Inventory bookkeeping must never fail the walk pipeline.

package/Server/Utils/Telemetry/EntityRegistry.ts

@@ -217,7 +217,17 @@ export async function reconcileEntityRegistryThrottled(data: {
   try {
     const promoted: Array<ExtractedEntity> = data.entities.filter(
       (entity: ExtractedEntity) => {
-        return REGISTRY_PROMOTED_TYPES.has(entity.entityType);
+        /*
+         * Two gates, and they answer different questions. The type gate asks
+         * "does this KIND of thing belong in the registry"; the per-entity
+         * flag asks "is this particular observation the resource's entity of
+         * that type, or a duplicate the producer sent alongside it". See
+         * `ExtractedEntity.membershipOnly`.
+         */
+        return (
+          !entity.membershipOnly &&
+          REGISTRY_PROMOTED_TYPES.has(entity.entityType)
+        );
       },
     );
     const retiredHosts: Array<RetiredEntityIdentity> = (

package/Server/Utils/Telemetry/TelemetryEntity.ts

@@ -82,6 +82,20 @@ export interface ExtractedEntity {
    * the registry attaches them via the existing project label system.
    */
   labels?: Array<string>;
+  /**
+   * When true this entity contributes its key to `entityKeys` on signals but
+   * must never mint a registry row.
+   *
+   * One OTLP resource describes ONE object of any given type — it is a single
+   * pod, on a single node, in a single cluster — and the rest of the pipeline
+   * relies on that: `scalarEntityKeysFromEntities` keeps the first key per
+   * type, and the heuristic resolvers emit at most one entity per type by
+   * construction. A producer can nonetheless send two `entity_refs` of the
+   * same type on one resource, and promoting both put two rows in Inventory
+   * from a single batch. The extra refs stay queryable as membership keys and
+   * stop there.
+   */
+  membershipOnly?: boolean;
 }
 
 /**
@@ -302,6 +316,12 @@ export default class InventoryItem {
   }): Array<ExtractedEntity> {
     const out: Array<ExtractedEntity> = [];
     const seen: Set<string> = new Set<string>();
+    /*
+     * First usable ref of a type is the one that gets a registry row; any
+     * later ref of that same type is demoted to membership-only. See
+     * `ExtractedEntity.membershipOnly`.
+     */
+    const promotedTypes: Set<EntityType> = new Set<EntityType>();
 
     for (const ref of data.entityRefs) {
       const refType: string =
@@ -381,6 +401,15 @@ export default class InventoryItem {
         }
       }
 
+      const alreadyPromoted: boolean = promotedTypes.has(entityType);
+      if (alreadyPromoted) {
+        logger.debug(
+          `OTLP resource declares more than one entity_ref of type "${refType}"; keeping the first as the entity and the rest as membership keys only.`,
+        );
+      } else {
+        promotedTypes.add(entityType);
+      }
+
       out.push({
         entityType,
         entityKey,
@@ -388,6 +417,7 @@ export default class InventoryItem {
         ...(Object.keys(descriptiveAttributes).length > 0
           ? { descriptiveAttributes }
           : {}),
+        ...(alreadyPromoted ? { membershipOnly: true } : {}),
       });
     }
 
@@ -570,7 +600,32 @@ export default class InventoryItem {
       return { entityType: EntityType.KubernetesNamespace, id };
     },
 
-    // k8s.node — cluster + k8s.node.uid/k8s.node.name.
+    /*
+     * k8s.node — cluster + k8s.node.name, falling back to k8s.node.uid only
+     * when no name is available.
+     *
+     * The name is preferred BECAUSE the uid is not universally reported and
+     * identity must not depend on which optional attributes a particular
+     * producer happens to carry. The shipped Kubernetes agent proves the
+     * point: its Deployment collector's `k8s_cluster` receiver reports node
+     * metrics with uid AND name, while its DaemonSet collector
+     * (kubeletstats / hostmetrics / cAdvisor / filelog) only ever has the
+     * name — the kubelet summary API carries no node uid and `k8sattributes`
+     * is not asked to extract one. A uid-first rule therefore hashed the same
+     * node two ways and put two rows in Inventory, both `discovered`, both
+     * displaying the same node name (`k8s.node.name` is a descriptive
+     * attribute on the uid-keyed row, so the two were indistinguishable in
+     * the list). Neither row aged out, because both pipelines keep reporting.
+     *
+     * Name-keying is also what the rest of OneUptime already assumes: the
+     * chart's own comment at configmap-daemonset.yaml says "OneUptime keys the
+     * k8s.node entity on k8s.cluster.name + k8s.node.name", and cluster and
+     * host identity are name-based for the same reason (see
+     * k8sClusterIdentity and the host resolver above).
+     *
+     * The uid stays available as a descriptive attribute, and remains the
+     * identity for the one resource that genuinely has nothing else.
+     */
     (attrs: EntityAttributes) => {
       const nodeUid: string | null = InventoryItem.str(attrs, "k8s.node.uid");
       const nodeName: string | null = InventoryItem.str(attrs, "k8s.node.name");
@@ -580,15 +635,27 @@ export default class InventoryItem {
       const id: Dictionary<string> = {
         ...(InventoryItem.k8sClusterIdentity(attrs) || {}),
       };
-      if (nodeUid) {
-        id["k8s.node.uid"] = nodeUid;
-      } else if (nodeName) {
+      if (nodeName) {
         id["k8s.node.name"] = nodeName;
+      } else {
+        id["k8s.node.uid"] = nodeUid!;
       }
       return { entityType: EntityType.KubernetesNode, id };
     },
 
-    // k8s.pod — cluster + namespace + k8s.pod.uid/k8s.pod.name.
+    /*
+     * k8s.pod — cluster + namespace + k8s.pod.name, falling back to
+     * k8s.pod.uid only when no name is available. Name-preferring for the
+     * same reason as k8s.node above: a pod observed by one pipeline that
+     * resolves its uid and another that does not is one pod, not two.
+     *
+     * A pod name is unique within a namespace at any instant, so this also
+     * makes a restarted StatefulSet pod (same name, new uid) stay one
+     * inventory row instead of minting a fresh one per incarnation — which
+     * is the behaviour an inventory wants. Incarnations remain separable on
+     * the signals themselves, which still carry `k8s.pod.uid` as a resource
+     * attribute, and the 24h pod TTL still reaps a name that stops reporting.
+     */
     (attrs: EntityAttributes) => {
       const podUid: string | null = InventoryItem.str(attrs, "k8s.pod.uid");
       const podName: string | null = InventoryItem.str(attrs, "k8s.pod.name");
@@ -599,10 +666,10 @@ export default class InventoryItem {
         ...(InventoryItem.k8sClusterIdentity(attrs) || {}),
       };
       InventoryItem.addIfPresent(id, attrs, "k8s.namespace.name");
-      if (podUid) {
-        id["k8s.pod.uid"] = podUid;
-      } else if (podName) {
+      if (podName) {
         id["k8s.pod.name"] = podName;
+      } else {
+        id["k8s.pod.uid"] = podUid!;
       }
       return { entityType: EntityType.KubernetesPod, id };
     },
@@ -820,11 +887,18 @@ export default class InventoryItem {
       "telemetry.sdk.name",
       "telemetry.sdk.version",
     ],
+    /*
+     * The uids are descriptive rather than identifying (see the node / pod
+     * resolvers): keeping them here means the Inventory row still shows the
+     * uid of the object it is currently tracking, without that uid being able
+     * to fork the row's identity.
+     */
     [EntityType.KubernetesNode]: [
       "k8s.node.name",
+      "k8s.node.uid",
       "node.kubernetes.io/instance-type",
     ],
-    [EntityType.KubernetesPod]: ["k8s.pod.name"],
+    [EntityType.KubernetesPod]: ["k8s.pod.name", "k8s.pod.uid"],
     [EntityType.Container]: [
       "container.image.name",
       "container.image.tag",

package/Tests/App/Dashboard/AddNeighborToMonitoringModal.test.tsx

@@ -530,3 +530,35 @@ describe("the Add to Monitoring dialog", () => {
     }
   });
 });
+
+/*
+ * The MAC the map already knows for a neighbour rides into the create form,
+ * so a device adopted from the drawer keeps its switch port from its first
+ * poll rather than waiting for a router's ARP table to say it again.
+ */
+describe("the MAC Address the map knows is pre-filled", () => {
+  beforeEach(() => {
+    captured = null;
+    neighborQueries = [];
+    neighborRows = [{ _id: "switch-1", probeId: "probe-a", siteId: "site-a" }];
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  test("a neighbour with a known MAC opens with it filled in", async () => {
+    const props: CapturedModalProps = await openDialog({
+      ...PHONE_NODE,
+      macAddress: "aa:bb:cc:dd:ee:01",
+    });
+
+    expect(props.initialValues["macAddress"]).toBe("aa:bb:cc:dd:ee:01");
+  });
+
+  test("a neighbour with no known MAC opens with the field empty", async () => {
+    const props: CapturedModalProps = await openDialog(PHONE_NODE);
+
+    expect(props.initialValues["macAddress"]).toBeUndefined();
+  });
+});