@oneuptime/common 11.5.13 → 11.6.1

package/Tests/Types/Monitor/MonitorStepMetricViewConfigUtil.test.ts

@@ -0,0 +1,245 @@
+import MetricFormulaConfigData from "../../../Types/Metrics/MetricFormulaConfigData";
+import MetricQueryConfigData from "../../../Types/Metrics/MetricQueryConfigData";
+import MetricsViewConfig from "../../../Types/Metrics/MetricsViewConfig";
+import { MonitorStepType } from "../../../Types/Monitor/MonitorStep";
+import MonitorStepMetricViewConfigUtil from "../../../Types/Monitor/MonitorStepMetricViewConfigUtil";
+
+/*
+ * Regression coverage for the "No options" metric dropdown bug.
+ *
+ * The alert-criteria "Which metric query should this alert rule check?"
+ * dropdown is populated from whichever metric-shaped monitor sub-config is
+ * present on the step. Before this util existed the resolution was an inline
+ * OR-chain that only read metricMonitor / kubernetesMonitor / dockerMonitor /
+ * proxmoxMonitor / cephMonitor — so Host, Podman, DockerSwarm and IoT monitors
+ * (all of which DO carry a metricViewConfig) surfaced ZERO options even though
+ * their step forms had populated real query configs.
+ *
+ * These tests lock in that EVERY metric-shaped key is resolved, and that the
+ * variable-collection semantics (dedup, drop-empty, include formulas) match
+ * what the dropdown expects.
+ */
+
+// Every monitor-step key that carries a metricViewConfig.
+const METRIC_SHAPED_KEYS: Array<keyof MonitorStepType> = [
+  "metricMonitor",
+  "hostMonitor",
+  "kubernetesMonitor",
+  "dockerMonitor",
+  "dockerSwarmMonitor",
+  "podmanMonitor",
+  "proxmoxMonitor",
+  "cephMonitor",
+  "iotMonitor",
+];
+
+function queryWithVariable(
+  metricVariable: string,
+  groupByAttributeKeys?: Array<string>,
+): MetricQueryConfigData {
+  return {
+    metricAliasData: {
+      metricVariable,
+      title: metricVariable,
+      description: metricVariable,
+      legend: metricVariable,
+      legendUnit: undefined,
+    },
+    metricQueryData: {
+      filterData: {},
+      groupByAttributeKeys,
+    },
+  } as unknown as MetricQueryConfigData;
+}
+
+function formulaWithVariable(metricVariable: string): MetricFormulaConfigData {
+  return {
+    metricAliasData: {
+      metricVariable,
+      title: metricVariable,
+      description: metricVariable,
+      legend: metricVariable,
+      legendUnit: undefined,
+    },
+    metricFormulaData: {
+      metricFormula: "a + b",
+    },
+  } as unknown as MetricFormulaConfigData;
+}
+
+function viewConfig(
+  queryVariables: Array<string>,
+  formulaVariables: Array<string> = [],
+): MetricsViewConfig {
+  return {
+    queryConfigs: queryVariables.map((v: string) => {
+      return queryWithVariable(v);
+    }),
+    formulaConfigs: formulaVariables.map((v: string) => {
+      return formulaWithVariable(v);
+    }),
+  };
+}
+
+function stepDataWith(
+  key: keyof MonitorStepType,
+  config: MetricsViewConfig,
+): MonitorStepType {
+  return {
+    [key]: {
+      metricViewConfig: config,
+    },
+  } as unknown as MonitorStepType;
+}
+
+describe("MonitorStepMetricViewConfigUtil", () => {
+  describe("getMetricViewConfig", () => {
+    test("returns undefined for undefined step data", () => {
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricViewConfig(undefined),
+      ).toBeUndefined();
+    });
+
+    test("returns undefined for a non-metric-shaped monitor step", () => {
+      const stepData: MonitorStepType = {
+        logMonitor: { someField: true },
+      } as unknown as MonitorStepType;
+
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricViewConfig(stepData),
+      ).toBeUndefined();
+    });
+
+    test("returns undefined when the metric sub-config has no metricViewConfig", () => {
+      const stepData: MonitorStepType = {
+        hostMonitor: { hostIdentifier: "h-1" },
+      } as unknown as MonitorStepType;
+
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricViewConfig(stepData),
+      ).toBeUndefined();
+    });
+
+    // The core of the bug: each metric-shaped key must be resolvable.
+    test.each(METRIC_SHAPED_KEYS)(
+      "resolves metricViewConfig from %s",
+      (key: keyof MonitorStepType) => {
+        const config: MetricsViewConfig = viewConfig(["a"]);
+        const stepData: MonitorStepType = stepDataWith(key, config);
+
+        expect(
+          MonitorStepMetricViewConfigUtil.getMetricViewConfig(stepData),
+        ).toBe(config);
+      },
+    );
+
+    test("prefers metricMonitor when multiple metric configs are present", () => {
+      const metricConfig: MetricsViewConfig = viewConfig(["metric"]);
+      const hostConfig: MetricsViewConfig = viewConfig(["host"]);
+      const stepData: MonitorStepType = {
+        metricMonitor: { metricViewConfig: metricConfig },
+        hostMonitor: { metricViewConfig: hostConfig },
+      } as unknown as MonitorStepType;
+
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricViewConfig(stepData),
+      ).toBe(metricConfig);
+    });
+  });
+
+  describe("getMetricVariables", () => {
+    test("returns [] for undefined step data", () => {
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricVariables(undefined),
+      ).toEqual([]);
+    });
+
+    test("returns [] for a non-metric-shaped monitor step", () => {
+      const stepData: MonitorStepType = {
+        dnsMonitor: {},
+      } as unknown as MonitorStepType;
+
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricVariables(stepData),
+      ).toEqual([]);
+    });
+
+    /*
+     * Each metric-shaped key must surface its query variables (this is
+     * exactly the option list the criteria "Metric" dropdown renders).
+     */
+    test.each(METRIC_SHAPED_KEYS)(
+      "surfaces query variables from %s",
+      (key: keyof MonitorStepType) => {
+        const stepData: MonitorStepType = stepDataWith(
+          key,
+          viewConfig(["cpu", "memory"]),
+        );
+
+        expect(
+          MonitorStepMetricViewConfigUtil.getMetricVariables(stepData),
+        ).toEqual(["cpu", "memory"]);
+      },
+    );
+
+    test("includes formula variables after query variables", () => {
+      const stepData: MonitorStepType = stepDataWith(
+        "hostMonitor",
+        viewConfig(["a", "b"], ["c"]),
+      );
+
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricVariables(stepData),
+      ).toEqual(["a", "b", "c"]);
+    });
+
+    test("removes duplicate variables while preserving first-seen order", () => {
+      const stepData: MonitorStepType = stepDataWith(
+        "dockerMonitor",
+        viewConfig(["a", "a", "b"], ["b", "c"]),
+      );
+
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricVariables(stepData),
+      ).toEqual(["a", "b", "c"]);
+    });
+
+    test("drops empty and missing variables", () => {
+      const stepData: MonitorStepType = stepDataWith(
+        "podmanMonitor",
+        viewConfig(["a", "", "b"]),
+      );
+
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricVariables(stepData),
+      ).toEqual(["a", "b"]);
+    });
+
+    test("returns [] when queryConfigs and formulaConfigs are empty", () => {
+      const stepData: MonitorStepType = stepDataWith("iotMonitor", {
+        queryConfigs: [],
+        formulaConfigs: [],
+      });
+
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricVariables(stepData),
+      ).toEqual([]);
+    });
+
+    /*
+     * Custom Metric flow: the alias is the (possibly long) metric id with
+     * dashes swapped for underscores, e.g. process_cpu_utilization. The
+     * dropdown must still offer it.
+     */
+    test("surfaces a long descriptive alias from the custom-metric flow", () => {
+      const stepData: MonitorStepType = stepDataWith(
+        "hostMonitor",
+        viewConfig(["process_cpu_utilization"]),
+      );
+
+      expect(
+        MonitorStepMetricViewConfigUtil.getMetricVariables(stepData),
+      ).toEqual(["process_cpu_utilization"]);
+    });
+  });
+});

package/Tests/Types/Monitor/MonitorStepNetworkDeviceMonitor.test.ts

@@ -0,0 +1,155 @@
+import { JSONObject } from "../../../Types/JSON";
+import MonitorStepNetworkDeviceMonitor, {
+  MonitorStepNetworkDeviceMonitorUtil,
+} from "../../../Types/Monitor/MonitorStepNetworkDeviceMonitor";
+import SnmpOid from "../../../Types/Monitor/SnmpMonitor/SnmpOid";
+
+describe("MonitorStepNetworkDeviceMonitorUtil", () => {
+  describe("getDefault", () => {
+    test("returns no device, interface monitoring on, and no oids", () => {
+      const def: MonitorStepNetworkDeviceMonitor =
+        MonitorStepNetworkDeviceMonitorUtil.getDefault();
+
+      expect(def.networkDeviceId).toBeUndefined();
+      expect(def.monitorInterfaces).toBe(true);
+      expect(def.oids).toEqual([]);
+    });
+  });
+
+  describe("fromJSON", () => {
+    test("reads the fields from a full JSON object", () => {
+      const monitor: MonitorStepNetworkDeviceMonitor =
+        MonitorStepNetworkDeviceMonitorUtil.fromJSON({
+          networkDeviceId: "device-1",
+          monitorInterfaces: false,
+          oids: [
+            {
+              oid: "1.3.6.1.2.1.1.1.0",
+              name: "sysDescr",
+              description: "System Description",
+            },
+          ],
+        });
+
+      expect(monitor.networkDeviceId).toBe("device-1");
+      expect(monitor.monitorInterfaces).toBe(false);
+      expect(monitor.oids.length).toBe(1);
+      expect(monitor.oids[0]!.oid).toBe("1.3.6.1.2.1.1.1.0");
+      expect(monitor.oids[0]!.name).toBe("sysDescr");
+      expect(monitor.oids[0]!.description).toBe("System Description");
+    });
+
+    test("defaults monitorInterfaces to true unless it is explicitly false", () => {
+      // Missing -> true.
+      expect(
+        MonitorStepNetworkDeviceMonitorUtil.fromJSON({}).monitorInterfaces,
+      ).toBe(true);
+      // Any non-false value (e.g. a truthy) -> true.
+      expect(
+        MonitorStepNetworkDeviceMonitorUtil.fromJSON({
+          monitorInterfaces: true,
+        }).monitorInterfaces,
+      ).toBe(true);
+      // Explicit false -> false.
+      expect(
+        MonitorStepNetworkDeviceMonitorUtil.fromJSON({
+          monitorInterfaces: false,
+        }).monitorInterfaces,
+      ).toBe(false);
+    });
+
+    test("coerces a missing networkDeviceId to undefined and missing oids to []", () => {
+      const monitor: MonitorStepNetworkDeviceMonitor =
+        MonitorStepNetworkDeviceMonitorUtil.fromJSON({});
+
+      expect(monitor.networkDeviceId).toBeUndefined();
+      expect(monitor.oids).toEqual([]);
+    });
+
+    test("fills missing oid sub-fields with sensible defaults", () => {
+      const monitor: MonitorStepNetworkDeviceMonitor =
+        MonitorStepNetworkDeviceMonitorUtil.fromJSON({
+          oids: [{}, { oid: "1.2.3" }],
+        });
+
+      // A row with no oid string becomes an empty oid, name/description undefined.
+      expect(monitor.oids[0]!.oid).toBe("");
+      expect(monitor.oids[0]!.name).toBeUndefined();
+      expect(monitor.oids[0]!.description).toBeUndefined();
+      expect(monitor.oids[1]!.oid).toBe("1.2.3");
+    });
+  });
+
+  describe("toJSON", () => {
+    test("serializes each field including nested oids", () => {
+      const monitor: MonitorStepNetworkDeviceMonitor = {
+        networkDeviceId: "device-42",
+        monitorInterfaces: false,
+        oids: [{ oid: "1.2.3", name: "n", description: "d" }],
+      };
+
+      const json: JSONObject =
+        MonitorStepNetworkDeviceMonitorUtil.toJSON(monitor);
+
+      expect(json["networkDeviceId"]).toBe("device-42");
+      expect(json["monitorInterfaces"]).toBe(false);
+      expect(json["oids"]).toEqual([
+        { oid: "1.2.3", name: "n", description: "d" },
+      ]);
+    });
+  });
+
+  describe("round trip", () => {
+    test("fromJSON(toJSON(x)) preserves a fully-populated monitor", () => {
+      const original: MonitorStepNetworkDeviceMonitor = {
+        networkDeviceId: "device-7",
+        monitorInterfaces: false,
+        oids: [
+          { oid: "1.3.6.1.2.1.1.1.0", name: "sysDescr", description: "desc" },
+          {
+            oid: "1.3.6.1.2.1.1.3.0",
+            name: "sysUpTime",
+            description: "uptime",
+          },
+        ],
+      };
+
+      const roundTripped: MonitorStepNetworkDeviceMonitor =
+        MonitorStepNetworkDeviceMonitorUtil.fromJSON(
+          MonitorStepNetworkDeviceMonitorUtil.toJSON(original),
+        );
+
+      expect(roundTripped).toEqual(original);
+    });
+
+    test("the default value round-trips unchanged", () => {
+      const def: MonitorStepNetworkDeviceMonitor =
+        MonitorStepNetworkDeviceMonitorUtil.getDefault();
+
+      const roundTripped: MonitorStepNetworkDeviceMonitor =
+        MonitorStepNetworkDeviceMonitorUtil.fromJSON(
+          MonitorStepNetworkDeviceMonitorUtil.toJSON(def),
+        );
+
+      expect(roundTripped).toEqual(def);
+    });
+
+    test("preserves oids with only an oid string across a round trip", () => {
+      const original: MonitorStepNetworkDeviceMonitor = {
+        networkDeviceId: undefined,
+        monitorInterfaces: true,
+        oids: [{ oid: "1.2.3", name: undefined, description: undefined }],
+      };
+
+      const roundTripped: MonitorStepNetworkDeviceMonitor =
+        MonitorStepNetworkDeviceMonitorUtil.fromJSON(
+          MonitorStepNetworkDeviceMonitorUtil.toJSON(original),
+        );
+
+      const oid: SnmpOid = roundTripped.oids[0]!;
+      expect(oid.oid).toBe("1.2.3");
+      expect(oid.name).toBeUndefined();
+      expect(oid.description).toBeUndefined();
+    });
+  });
+});

package/Tests/Types/Monitor/MonitorStepTelemetrySerialization.test.ts

@@ -0,0 +1,141 @@
+import MonitorStep from "../../../Types/Monitor/MonitorStep";
+import MonitorType from "../../../Types/Monitor/MonitorType";
+import ObjectID from "../../../Types/ObjectID";
+import LogSeverity from "../../../Types/Log/LogSeverity";
+import MonitorStepLogMonitor from "../../../Types/Monitor/MonitorStepLogMonitor";
+import { JSONObject } from "../../../Types/JSON";
+
+/*
+ * Guards the persistence half of the "log monitors do not work" fix. The bug
+ * hinged on MonitorStep.toJSON() serializing a sub-config only when it is
+ * truthy: a step whose logMonitor was undefined serialized to no logMonitor at
+ * all, so the config was silently dropped on save and the worker later saw an
+ * empty config. These tests prove (a) a seeded telemetry sub-config survives a
+ * toJSON -> fromJSON round-trip, (b) user-entered filters survive it, and
+ * (c) the drop-when-undefined behavior the bug relied on is real (so the seed
+ * is what prevents it).
+ */
+
+const buildArgs: (
+  monitorType: MonitorType,
+) => Parameters<typeof MonitorStep.getDefaultMonitorStep>[0] = (
+  monitorType: MonitorType,
+) => {
+  const id: ObjectID = ObjectID.generate();
+  return {
+    monitorName: `${monitorType} monitor`,
+    monitorType,
+    onlineMonitorStatusId: id,
+    offlineMonitorStatusId: id,
+    defaultIncidentSeverityId: id,
+    defaultAlertSeverityId: id,
+  };
+};
+
+const serializedValue: (step: MonitorStep) => JSONObject = (
+  step: MonitorStep,
+): JSONObject => {
+  return step.toJSON()["value"] as JSONObject;
+};
+
+const roundTrip: (step: MonitorStep) => MonitorStep = (
+  step: MonitorStep,
+): MonitorStep => {
+  return MonitorStep.fromJSON(step.toJSON());
+};
+
+describe("MonitorStep telemetry sub-config serialization round-trip", () => {
+  test("a default Logs step keeps its logMonitor through toJSON/fromJSON", () => {
+    const step: MonitorStep = MonitorStep.getDefaultMonitorStep(
+      buildArgs(MonitorType.Logs),
+    );
+
+    // Serialized output must actually contain the sub-config...
+    const logMonitorJson: JSONObject = serializedValue(step)[
+      "logMonitor"
+    ] as JSONObject;
+    expect(logMonitorJson).toBeDefined();
+    expect(logMonitorJson["lastXSecondsOfLogs"]).toBeGreaterThan(0);
+
+    // ...and it must survive a round-trip back into a MonitorStep.
+    expect(roundTrip(step).data?.logMonitor).toBeDefined();
+  });
+
+  test.each([
+    [MonitorType.Traces, "traceMonitor"],
+    [MonitorType.Metrics, "metricMonitor"],
+    [MonitorType.Exceptions, "exceptionMonitor"],
+  ])(
+    "a default %s step keeps its %s",
+    (monitorType: MonitorType, key: string) => {
+      const step: MonitorStep = MonitorStep.getDefaultMonitorStep(
+        buildArgs(monitorType),
+      );
+
+      expect(serializedValue(step)[key]).toBeDefined();
+      expect(
+        (roundTrip(step).data as unknown as JSONObject)[key],
+      ).toBeDefined();
+    },
+  );
+
+  test("user-entered log filters are written to the persisted form", () => {
+    const serviceId: ObjectID = ObjectID.generate();
+    const step: MonitorStep = MonitorStep.getDefaultMonitorStep(
+      buildArgs(MonitorType.Logs),
+    );
+
+    const custom: MonitorStepLogMonitor = {
+      attributes: { env: "prod" },
+      body: "connection refused",
+      severityTexts: [LogSeverity.Error, LogSeverity.Fatal],
+      telemetryServiceIds: [serviceId],
+      entityKeys: ["host-1"],
+      lastXSecondsOfLogs: 300,
+    };
+    step.setLogMonitor(custom);
+
+    // The canonical persisted form (toJSON) carries every filter the user set.
+    const logMonitorJson: JSONObject = serializedValue(step)[
+      "logMonitor"
+    ] as JSONObject;
+    expect(logMonitorJson["body"]).toBe("connection refused");
+    expect(logMonitorJson["severityTexts"]).toEqual([
+      LogSeverity.Error,
+      LogSeverity.Fatal,
+    ]);
+    expect(logMonitorJson["attributes"]).toEqual({ env: "prod" });
+    expect(logMonitorJson["entityKeys"]).toEqual(["host-1"]);
+    expect(logMonitorJson["lastXSecondsOfLogs"]).toBe(300);
+    expect(
+      (logMonitorJson["telemetryServiceIds"] as Array<unknown>).length,
+    ).toBe(1);
+
+    // And the config still deserializes back onto the step.
+    expect(roundTrip(step).data?.logMonitor).toBeDefined();
+  });
+
+  test("the drop-when-undefined behavior the bug relied on is real", () => {
+    /*
+     * A Ping monitor has no telemetry sub-config. Its serialized form must
+     * not carry logMonitor/traceMonitor/etc, and the round-trip returns
+     * undefined for them. This is exactly why leaving the config undefined
+     * (pre-fix) lost it on save — and why seeding it (the fix) is required.
+     */
+    const step: MonitorStep = MonitorStep.getDefaultMonitorStep(
+      buildArgs(MonitorType.Ping),
+    );
+
+    const value: JSONObject = serializedValue(step);
+    expect(value["logMonitor"]).toBeUndefined();
+    expect(value["traceMonitor"]).toBeUndefined();
+    expect(value["metricMonitor"]).toBeUndefined();
+    expect(value["exceptionMonitor"]).toBeUndefined();
+
+    const restored: MonitorStep = roundTrip(step);
+    expect(restored.data?.logMonitor).toBeUndefined();
+    expect(restored.data?.traceMonitor).toBeUndefined();
+    expect(restored.data?.metricMonitor).toBeUndefined();
+    expect(restored.data?.exceptionMonitor).toBeUndefined();
+  });
+});

package/Tests/Types/Monitor/MonitorStepTraceMonitor.test.ts

@@ -0,0 +1,137 @@
+import Span, { SpanStatus } from "../../../Models/AnalyticsModels/Span";
+import Includes from "../../../Types/BaseDatabase/Includes";
+import InBetween from "../../../Types/BaseDatabase/InBetween";
+import Query from "../../../Types/BaseDatabase/Query";
+import Search from "../../../Types/BaseDatabase/Search";
+import MonitorStepTraceMonitor, {
+  MonitorStepTraceMonitorUtil,
+} from "../../../Types/Monitor/MonitorStepTraceMonitor";
+import ObjectID from "../../../Types/ObjectID";
+
+/*
+ * Parity coverage for the trace monitor step util. monitorTrace() now falls
+ * back to MonitorStepTraceMonitorUtil.getDefault() when a step was saved with
+ * no config, so getDefault() must produce a query that toQuery() turns into a
+ * valid, minimal Span query (just a trailing time window).
+ */
+describe("MonitorStepTraceMonitorUtil", () => {
+  describe("getDefault", () => {
+    test("returns an empty monitor scoped to the last 60 seconds", () => {
+      const def: MonitorStepTraceMonitor =
+        MonitorStepTraceMonitorUtil.getDefault();
+
+      expect(def.attributes).toEqual({});
+      expect(def.spanName).toBe("");
+      expect(def.spanStatuses).toEqual([]);
+      expect(def.telemetryServiceIds).toEqual([]);
+      expect(def.entityKeys).toEqual([]);
+      expect(def.lastXSecondsOfSpans).toBe(60);
+    });
+
+    test("toQuery(getDefault()) is a valid minimal query (time window only)", () => {
+      const query: Query<Span> = MonitorStepTraceMonitorUtil.toQuery(
+        MonitorStepTraceMonitorUtil.getDefault(),
+      );
+
+      // Only the trailing time window is set; no over-scoping filters.
+      expect(query.startTime).toBeInstanceOf(InBetween);
+      expect(query.primaryEntityId).toBeUndefined();
+      expect(query.entityKeys).toBeUndefined();
+      expect(query.attributes).toBeUndefined();
+      expect(query.statusCode).toBeUndefined();
+      expect(query.name).toBeUndefined();
+    });
+  });
+
+  describe("toQuery", () => {
+    test("builds no filters for an empty monitor with the time window off", () => {
+      const query: Query<Span> = MonitorStepTraceMonitorUtil.toQuery({
+        ...MonitorStepTraceMonitorUtil.getDefault(),
+        lastXSecondsOfSpans: 0,
+      });
+      expect(query).toEqual({});
+    });
+
+    test("scopes to telemetry services when provided", () => {
+      const serviceId: ObjectID = ObjectID.generate();
+      const query: Query<Span> = MonitorStepTraceMonitorUtil.toQuery({
+        ...MonitorStepTraceMonitorUtil.getDefault(),
+        telemetryServiceIds: [serviceId],
+        lastXSecondsOfSpans: 0,
+      });
+      expect(query.primaryEntityId).toBeInstanceOf(Includes);
+      expect((query.primaryEntityId as Includes).values).toEqual([serviceId]);
+    });
+
+    test("scopes to entity keys when provided", () => {
+      const query: Query<Span> = MonitorStepTraceMonitorUtil.toQuery({
+        ...MonitorStepTraceMonitorUtil.getDefault(),
+        entityKeys: ["host-1"],
+        lastXSecondsOfSpans: 0,
+      });
+      expect(query.entityKeys).toBeInstanceOf(Includes);
+      expect((query.entityKeys as Includes).values).toEqual(["host-1"]);
+    });
+
+    test("filters by span status when provided", () => {
+      const query: Query<Span> = MonitorStepTraceMonitorUtil.toQuery({
+        ...MonitorStepTraceMonitorUtil.getDefault(),
+        spanStatuses: [SpanStatus.Error],
+        lastXSecondsOfSpans: 0,
+      });
+      expect(query.statusCode).toBeInstanceOf(Includes);
+      expect((query.statusCode as Includes).values).toEqual([SpanStatus.Error]);
+    });
+
+    test("searches the span name when provided", () => {
+      const query: Query<Span> = MonitorStepTraceMonitorUtil.toQuery({
+        ...MonitorStepTraceMonitorUtil.getDefault(),
+        spanName: "GET /checkout",
+        lastXSecondsOfSpans: 0,
+      });
+      expect(query.name).toBeInstanceOf(Search);
+      expect((query.name as Search<string>).value).toBe("GET /checkout");
+    });
+
+    test("builds a trailing time window from lastXSecondsOfSpans", () => {
+      const query: Query<Span> = MonitorStepTraceMonitorUtil.toQuery({
+        ...MonitorStepTraceMonitorUtil.getDefault(),
+        lastXSecondsOfSpans: 120,
+      });
+      expect(query.startTime).toBeInstanceOf(InBetween);
+      const time: InBetween<Date> = query.startTime as InBetween<Date>;
+      const spanMs: number =
+        time.endValue.getTime() - time.startValue.getTime();
+      expect(Math.abs(spanMs - 120 * 1000)).toBeLessThan(2000);
+    });
+  });
+
+  describe("toJSON / fromJSON", () => {
+    test("round-trips a fully populated monitor", () => {
+      const original: MonitorStepTraceMonitor = {
+        attributes: { env: "prod" },
+        spanName: "GET /checkout",
+        spanStatuses: [SpanStatus.Error, SpanStatus.Ok],
+        telemetryServiceIds: [ObjectID.generate()],
+        entityKeys: ["host-1"],
+        lastXSecondsOfSpans: 300,
+      };
+
+      const roundTripped: MonitorStepTraceMonitor =
+        MonitorStepTraceMonitorUtil.fromJSON(
+          MonitorStepTraceMonitorUtil.toJSON(original),
+        );
+
+      expect(roundTripped.attributes).toEqual(original.attributes);
+      expect(roundTripped.spanName).toBe(original.spanName);
+      expect(roundTripped.spanStatuses).toEqual(original.spanStatuses);
+      expect(roundTripped.entityKeys).toEqual(original.entityKeys);
+      expect(roundTripped.lastXSecondsOfSpans).toBe(
+        original.lastXSecondsOfSpans,
+      );
+      expect(roundTripped.telemetryServiceIds.map(String)).toEqual(
+        original.telemetryServiceIds.map(String),
+      );
+    });
+  });
+});