@oneuptime/common 14.0.3 → 14.0.5

package/Tests/Server/Utils/AI/ResourceTools.test.ts

@@ -12,6 +12,10 @@ import ServerlessFunctionService from "../../../../Server/Services/ServerlessFun
 import CloudResourceService from "../../../../Server/Services/CloudResourceService";
 import IoTFleetService from "../../../../Server/Services/IoTFleetService";
 import NetworkDeviceService from "../../../../Server/Services/NetworkDeviceService";
+import DatabaseServerService from "../../../../Server/Services/DatabaseServerService";
+import ResourceEntityFilter, {
+  ResourceEntityScope,
+} from "../../../../Server/Utils/Telemetry/ResourceEntityFilter";
 import MetricService, {
   MetricService as MetricServiceClass,
 } from "../../../../Server/Services/MetricService";
@@ -176,6 +180,21 @@ const cases: Array<ResourceCase> = [
     service: NetworkDeviceService,
     read: Permission.ReadNetworkDevice,
   },
+  {
+    type: AIResourceType.DatabaseServer,
+    service: DatabaseServerService,
+    read: Permission.ReadDatabaseServer,
+  },
+];
+
+/*
+ * A database's telemetry scope is its whole key set (endpoints + workload
+ * members), resolved by the same ResourceEntityFilter the explorer facet
+ * uses; stubbed here, and pinned to the parent id it was asked for.
+ */
+const DATABASE_ENTITY_KEYS: Array<string> = [
+  "0123456789abcdef",
+  "fedcba9876543210",
 ];
 
 function context(
@@ -259,11 +278,25 @@ let metric: jest.SpyInstance;
 let logs: jest.SpyInstance;
 let traces: jest.SpyInstance;
 let accessible: jest.SpyInstance;
+let resolveScopes: jest.SpyInstance;
 
 beforeEach(() => {
   for (const item of cases) {
     jest.spyOn(item.service, "findBy").mockResolvedValue([resource(item)]);
   }
+  resolveScopes = jest
+    .spyOn(ResourceEntityFilter, "resolveScopes")
+    .mockImplementation(
+      async (data: {
+        selections: Record<string, Array<string>>;
+      }): Promise<Array<ResourceEntityScope>> => {
+        return (data.selections["databaseServerId"] || []).map(
+          (id: string): ResourceEntityScope => {
+            return { entityIds: [id], entityKeys: DATABASE_ENTITY_KEYS };
+          },
+        );
+      },
+    );
   metric = jest
     .spyOn(MetricService, "aggregateBy")
     .mockResolvedValue({ data: [] });
@@ -775,6 +808,19 @@ describe("resource membership", () => {
             "resource.cloud.account.id": "account-1",
             "resource.cloud.region": "eu-west-1",
           });
+        } else if (item.type === AIResourceType.DatabaseServer) {
+          // Its own rows, plus every endpoint / member key it owns.
+          expect(scopes).toEqual([
+            {
+              entityIds: [resourceId.toString()],
+              entityKeys: DATABASE_ENTITY_KEYS,
+            },
+          ]);
+          expect(scopeQuery["attributes"]).toBeUndefined();
+          expect(resolveScopes).toHaveBeenLastCalledWith({
+            projectId,
+            selections: { databaseServerId: [resourceId.toString()] },
+          });
         } else if (signal === "logs") {
           expect(scopeQuery["attributes"]).toEqual({
             "networkDevice.id": resourceId.toString(),
@@ -821,6 +867,94 @@ describe("resource membership", () => {
     },
   );
 
+  test("a Database's key set is resolved only after its parent read succeeds", async () => {
+    (DatabaseServerService.findBy as jest.Mock).mockResolvedValue([]);
+
+    await expect(
+      QueryResourceTelemetryTool.execute(
+        args(AIResourceType.DatabaseServer, "logs"),
+        context(),
+      ),
+    ).rejects.toThrow("not found or you do not have access");
+    expect(resolveScopes).not.toHaveBeenCalled();
+    expect(logs).not.toHaveBeenCalled();
+  });
+
+  test("a Database scope that cannot be resolved narrows to the row's own data - never wider", () => {
+    for (const resolvedScopes of [
+      undefined,
+      [],
+      // Another row's scope is never borrowed.
+      [{ entityIds: [otherId.toString()], entityKeys: DATABASE_ENTITY_KEYS }],
+    ]) {
+      const scope: AIResourceTelemetryScope = buildAIResourceTelemetryScope({
+        type: AIResourceType.DatabaseServer,
+        id: resourceId,
+        projectId,
+        signal: "metrics",
+        resource: {},
+        resolvedScopes: resolvedScopes,
+      });
+      expect(scope.resourceScopes).toEqual([
+        { entityIds: [resourceId.toString()], entityKeys: [] },
+      ]);
+      expect(scope.attributes).toBeUndefined();
+    }
+  });
+
+  test("a Database scope explains what a database's telemetry is", async () => {
+    const result: ToolExecutionResult =
+      await QueryResourceTelemetryTool.execute(
+        args(AIResourceType.DatabaseServer, "traces"),
+        context(),
+      );
+    expect(result.dataForLlm).toContain(
+      "everything carrying one of its endpoints or workload members",
+    );
+    expect(result.citationTarget).toEqual({
+      type: AIChatCitationTargetType.TelemetryResourceView,
+      params: {
+        resourceType: AIResourceType.DatabaseServer,
+        resourceId: resourceId.toString(),
+      },
+    });
+  });
+
+  test("Database inventory reports the engine, version and endpoint - and nothing else", async () => {
+    (DatabaseServerService.findBy as jest.Mock).mockResolvedValue([
+      {
+        _id: resourceId.toString(),
+        name: "PostgreSQL orders-db:5432",
+        lastSeenAt: end,
+        isArchived: false,
+        otelCollectorStatus: "connected",
+        dbSystem: "postgresql",
+        dbVersion: "16.4",
+        serverAddress: "orders-db.example.com",
+        serverPort: 5432,
+        discoverySource: "kubernetes",
+        instanceCount: 3,
+        collectorLastSeenAt: end,
+        memberEntityKeys: { "0123456789abcdef": end.toISOString() },
+        automaticAssignments: { labelIds: ["secret-label"] },
+      },
+    ]);
+
+    const result: ToolExecutionResult =
+      await QueryTelemetryResourcesTool.execute(
+        { resourceType: AIResourceType.DatabaseServer },
+        context([Permission.ReadDatabaseServer]),
+      );
+
+    expect(result.dataForLlm).toContain("dbSystem=postgresql");
+    expect(result.dataForLlm).toContain("dbVersion=16.4");
+    expect(result.dataForLlm).toContain("serverPort=5432");
+    expect(result.dataForLlm).toContain("instanceCount=3");
+    expect(result.dataForLlm).not.toMatch(
+      /memberEntityKeys|0123456789abcdef|automaticAssignments|secret-label/,
+    );
+  });
+
   test("Cloud trims known attributes and omits absent account/region", () => {
     const scope: AIResourceTelemetryScope = buildAIResourceTelemetryScope({
       type: AIResourceType.CloudResource,

package/Tests/Server/Utils/Monitor/Criteria/MetricMonitorCriteria.test.ts

@@ -736,6 +736,47 @@ describe("MetricMonitorCriteria.evaluateAllSeries — per-host alerting", () =>
     expect(prod02.context.breachingSamples).toHaveLength(1);
     expect(prod01.context.seriesLabels).toEqual({ "host.name": "prod-01" });
   });
+
+  /*
+   * Grouped rows carry their labels nested under `attributes`. The map
+   * used to be copied through as one label called `attributes`, which the
+   * root cause's Breaching Samples list printed as "`attributes`:
+   * `[object Object]`". The raw-scan path also nests every OTHER datapoint
+   * attribute of the row there, so only the series' own labels come out.
+   */
+  test("breaching samples carry the series labels, not the nested attributes map", async () => {
+    const criteriaFilter: CriteriaFilter = {
+      checkOn: CheckOn.MetricValue,
+      filterType: FilterType.GreaterThan,
+      value: "80",
+      metricMonitorOptions: {
+        metricAlias: "a",
+        metricAggregationType: EvaluateOverTimeType.AnyValue,
+      },
+    };
+
+    const inputs: ReturnType<typeof buildInputsWithSeriesBreakdown> =
+      buildInputsWithSeriesBreakdown({
+        criteriaFilter,
+        seriesSamples: [{ labels: { "host.name": "prod-01" }, values: [95] }],
+      });
+
+    for (const row of inputs.dataToProcess.seriesBreakdown![0]!
+      .aggregatedResults[0]!.data) {
+      (row as unknown as { attributes: Record<string, string> }).attributes = {
+        "host.name": "prod-01",
+        "host.arch": "amd64",
+      };
+    }
+
+    const results: Awaited<
+      ReturnType<typeof MetricMonitorCriteria.evaluateAllSeries>
+    > = await MetricMonitorCriteria.evaluateAllSeries(inputs);
+
+    expect(results[0]!.context.breachingSamples?.[0]?.attributes).toEqual({
+      "host.name": "prod-01",
+    });
+  });
 });
 
 describe("MetricSeriesFingerprint", () => {

package/Tests/Server/Utils/Monitor/Criteria/MetricMonitorCriteriaAnomalyUnits.test.ts

@@ -34,6 +34,7 @@ import MetricQueryConfigData from "../../../../../Types/Metrics/MetricQueryConfi
 import MetricQueryData from "../../../../../Types/Metrics/MetricQueryData";
 import MetricsViewConfig from "../../../../../Types/Metrics/MetricsViewConfig";
 import MetricMonitorResponse from "../../../../../Types/Monitor/MetricMonitor/MetricMonitorResponse";
+import { MetricAnomalyBaseline } from "../../../../../Types/Monitor/MetricMonitor/MetricCriteriaContext";
 import MonitorStep from "../../../../../Types/Monitor/MonitorStep";
 import RollingTime from "../../../../../Types/RollingTime/RollingTime";
 import ObjectID from "../../../../../Types/ObjectID";
@@ -73,11 +74,26 @@ function baseline(): BaselineSummary {
   } as BaselineSummary;
 }
 
-function buildInputs(input: {
+interface AnomalyInputs {
   metricNativeUnit: string;
   metricName: string;
   sampleValue: number;
-}): {
+  /*
+   * The unit the user picked on the query alias. The worker has already
+   * converted samples into it; the baseline is still in the native unit.
+   * Defaults to the native unit (no conversion).
+   */
+  legendUnit?: string;
+  /*
+   * What the worker ships as MetricMonitorResponse.nativeUnitsByMetricName.
+   * Defaults to { <lowercased metric name>: metricNativeUnit }; pass null to
+   * model a payload from before the map existed.
+   */
+  nativeUnitsByMetricName?: { [key: string]: string } | null;
+  filterType?: FilterType;
+}
+
+function buildInputs(input: AnomalyInputs): {
   criteriaFilter: CriteriaFilter;
   monitorStep: MonitorStep;
   dataToProcess: MetricMonitorResponse;
@@ -88,7 +104,10 @@ function buildInputs(input: {
     title: input.metricName,
     description: undefined,
     legend: undefined,
-    legendUnit: input.metricNativeUnit,
+    legendUnit:
+      input.legendUnit !== undefined
+        ? input.legendUnit
+        : input.metricNativeUnit,
   };
 
   const queryConfig: MetricQueryConfigData = {
@@ -126,10 +145,17 @@ function buildInputs(input: {
 
   const projectId: ObjectID = ObjectID.generate();
 
+  const nativeUnitsByMetricName: { [key: string]: string } | undefined =
+    input.nativeUnitsByMetricName === null
+      ? undefined
+      : input.nativeUnitsByMetricName || {
+          [input.metricName.toLowerCase()]: input.metricNativeUnit,
+        };
+
   return {
     criteriaFilter: {
       checkOn: CheckOn.MetricValue,
-      filterType: FilterType.AnomalouslyHigh,
+      filterType: input.filterType || FilterType.AnomalouslyHigh,
       metricMonitorOptions: {
         metricAlias: "a",
       },
@@ -140,16 +166,16 @@ function buildInputs(input: {
       metricResult: [aggregated],
       metricViewConfig,
       monitorId: ObjectID.generate(),
+      nativeUnitsByMetricName,
     },
     projectId,
   };
 }
 
-async function anomalyRootCause(input: {
-  metricNativeUnit: string;
-  metricName: string;
-  sampleValue: number;
-}): Promise<string> {
+async function evaluateAnomaly(input: AnomalyInputs): Promise<{
+  message: string | null;
+  anomalyBaseline: MetricAnomalyBaseline | undefined;
+}> {
   const inputs: ReturnType<typeof buildInputs> = buildInputs(input);
 
   const message: string | null =
@@ -160,6 +186,16 @@ async function anomalyRootCause(input: {
       projectId: inputs.projectId,
     } as never);
 
+  return {
+    message,
+    anomalyBaseline:
+      inputs.criteriaFilter.metricCriteriaContext?.anomalyBaseline,
+  };
+}
+
+async function anomalyRootCause(input: AnomalyInputs): Promise<string> {
+  const { message } = await evaluateAnomaly(input);
+
   expect(message).toBeTruthy();
   return message as string;
 }
@@ -244,3 +280,237 @@ describe("MetricMonitorCriteria - anomaly root cause units", () => {
     expect(rootCause).not.toContain("0.85 1");
   });
 });
+
+/*
+ * THE BASELINE IS IN THE NATIVE UNIT; THE SAMPLES ARE NOT.
+ *
+ * The worker converts every sample from the metric's native unit into the
+ * query's legendUnit before criteria run. The baseline never goes through
+ * that step: the ClickHouse MV aggregates the raw stored values, so its
+ * mean and stddev stay in the native unit. With a legendUnit of "MB" on a
+ * native "By" metric, the evaluator used to compare a sample of ~1074 MB
+ * against a mean of 268435456 "MB" — and when something did get rendered
+ * it read "value 1.07 GB ... (mean 268 TB, σ 134 TB ...)".
+ */
+describe("MetricMonitorCriteria - anomaly baseline is converted into the sample unit", () => {
+  beforeEach(() => {
+    (MetricBaselineService.getBaseline as unknown as jest.Mock).mockReset();
+    (
+      MetricBaselineService.getBaseline as unknown as jest.Mock
+    ).mockResolvedValue(baseline() as never);
+  });
+
+  // 1 GiB, 256 MiB and 128 MiB expressed in decimal megabytes.
+  const BREACHING_VALUE_MB: number = BREACHING_VALUE / 1e6;
+  const BASELINE_MEAN_MB: number = BASELINE_MEAN / 1e6;
+  const BASELINE_STDDEV_MB: number = BASELINE_STDDEV / 1e6;
+
+  test("a native-bytes baseline is compared and rendered in the legend unit", async () => {
+    const { message, anomalyBaseline } = await evaluateAnomaly({
+      metricName: "container.memory.usage",
+      metricNativeUnit: "By",
+      legendUnit: "MB",
+      sampleValue: BREACHING_VALUE_MB,
+    });
+
+    expect(message).toBeTruthy();
+    const rootCause: string = message as string;
+
+    // Same scale on both sides of the comparison.
+    expect(rootCause).toContain("value 1.07 GB");
+    expect(rootCause).toContain("mean 268 MB");
+    expect(rootCause).toContain("σ 134 MB");
+    expect(rootCause).toContain("is 6.00σ above the same-hour baseline");
+
+    // The unconverted baseline read as megabytes.
+    expect(rootCause).not.toContain("TB");
+    expect(rootCause).not.toContain("PB");
+
+    expect(anomalyBaseline?.state).toBe("Anomalous");
+    expect(anomalyBaseline?.mean).toBeCloseTo(BASELINE_MEAN_MB, 6);
+    expect(anomalyBaseline?.stddev).toBeCloseTo(BASELINE_STDDEV_MB, 6);
+    expect(anomalyBaseline?.expectedHigh).toBeCloseTo(
+      BASELINE_MEAN_MB + 3 * BASELINE_STDDEV_MB,
+      6,
+    );
+    expect(anomalyBaseline?.expectedLow).toBeCloseTo(
+      BASELINE_MEAN_MB - 3 * BASELINE_STDDEV_MB,
+      6,
+    );
+    expect(anomalyBaseline?.observedValue).toBeCloseTo(BREACHING_VALUE_MB, 6);
+    expect(anomalyBaseline?.observedSigma).toBeCloseTo(6, 6);
+  });
+
+  /*
+   * Before the fix this sample could never breach: a ~1074 MB value sits
+   * far below a 268435456 "MB" mean, so an AnomalouslyHigh monitor on a
+   * legendUnit-converted metric was silently dead.
+   */
+  test("a real spike in the legend unit fires AnomalouslyHigh", async () => {
+    const { message } = await evaluateAnomaly({
+      metricName: "container.memory.usage",
+      metricNativeUnit: "By",
+      legendUnit: "MB",
+      sampleValue: BREACHING_VALUE_MB,
+      filterType: FilterType.AnomalouslyHigh,
+    });
+
+    expect(message).not.toBeNull();
+  });
+
+  /*
+   * ...and the mirror image: every legendUnit-scaled sample sat far below
+   * the native-unit mean, so AnomalouslyLow fired on a value that is
+   * exactly the baseline mean. A tight σ (1 MB) keeps the lower band
+   * positive, which is what let the old comparison fire.
+   */
+  const TIGHT_STDDEV: number = 1e6;
+
+  test("a value at the baseline mean does not fire AnomalouslyLow", async () => {
+    (
+      MetricBaselineService.getBaseline as unknown as jest.Mock
+    ).mockResolvedValue({
+      ...baseline(),
+      stddev: TIGHT_STDDEV,
+    } as never);
+
+    const { message, anomalyBaseline } = await evaluateAnomaly({
+      metricName: "container.memory.usage",
+      metricNativeUnit: "By",
+      legendUnit: "MB",
+      sampleValue: BASELINE_MEAN_MB,
+      filterType: FilterType.AnomalouslyLow,
+    });
+
+    expect(message).toBeNull();
+    expect(anomalyBaseline?.state).toBe("Normal");
+    expect(anomalyBaseline?.mean).toBeCloseTo(BASELINE_MEAN_MB, 6);
+    expect(anomalyBaseline?.stddev).toBeCloseTo(1, 6);
+    expect(anomalyBaseline?.expectedHigh).toBeCloseTo(BASELINE_MEAN_MB + 3, 6);
+    expect(anomalyBaseline?.expectedLow).toBeCloseTo(BASELINE_MEAN_MB - 3, 6);
+  });
+
+  test("a value at the baseline mean does not fire Anomalous", async () => {
+    (
+      MetricBaselineService.getBaseline as unknown as jest.Mock
+    ).mockResolvedValue({
+      ...baseline(),
+      stddev: TIGHT_STDDEV,
+    } as never);
+
+    const { message } = await evaluateAnomaly({
+      metricName: "container.memory.usage",
+      metricNativeUnit: "By",
+      legendUnit: "GB",
+      sampleValue: BASELINE_MEAN / 1e9,
+      filterType: FilterType.Anomalous,
+    });
+
+    expect(message).toBeNull();
+  });
+
+  test("a fraction baseline is compared against percent samples", async () => {
+    (
+      MetricBaselineService.getBaseline as unknown as jest.Mock
+    ).mockResolvedValue({
+      ...baseline(),
+      mean: 0.2,
+      stddev: 0.05,
+    } as never);
+
+    const { message, anomalyBaseline } = await evaluateAnomaly({
+      metricName: "system.cpu.utilization",
+      metricNativeUnit: "1",
+      legendUnit: "%",
+      sampleValue: 85,
+    });
+
+    expect(message).toBeTruthy();
+    expect(message).toContain("value 85.00%");
+    expect(message).toContain("mean 20.00%");
+    expect(message).toContain("σ 5.00%");
+    expect(message).toContain("is 13.00σ above");
+
+    expect(anomalyBaseline?.mean).toBeCloseTo(20, 6);
+    expect(anomalyBaseline?.stddev).toBeCloseTo(5, 6);
+  });
+
+  test("a native-seconds baseline is compared against millisecond samples", async () => {
+    (
+      MetricBaselineService.getBaseline as unknown as jest.Mock
+    ).mockResolvedValue({
+      ...baseline(),
+      mean: 0.2,
+      stddev: 0.1,
+    } as never);
+
+    const { message, anomalyBaseline } = await evaluateAnomaly({
+      metricName: "http.server.request.duration",
+      metricNativeUnit: "s",
+      legendUnit: "ms",
+      sampleValue: 1500,
+    });
+
+    expect(message).toBeTruthy();
+    expect(message).toContain("is 13.00σ above");
+    expect(anomalyBaseline?.mean).toBeCloseTo(200, 6);
+    expect(anomalyBaseline?.stddev).toBeCloseTo(100, 6);
+  });
+
+  /*
+   * The worker keys nativeUnitsByMetricName by the lowercased metric name;
+   * the criteria keeps the name as the user typed it.
+   */
+  test("the native unit is looked up case-insensitively", async () => {
+    const { message, anomalyBaseline } = await evaluateAnomaly({
+      metricName: "Container.Memory.Usage",
+      metricNativeUnit: "By",
+      legendUnit: "MB",
+      sampleValue: BREACHING_VALUE_MB,
+      nativeUnitsByMetricName: { "container.memory.usage": "By" },
+    });
+
+    expect(message).toBeTruthy();
+    expect(message).toContain("mean 268 MB");
+    expect(anomalyBaseline?.mean).toBeCloseTo(BASELINE_MEAN_MB, 6);
+  });
+
+  test("the baseline passes through unchanged when the native unit is unknown", async () => {
+    const { anomalyBaseline } = await evaluateAnomaly({
+      metricName: "container.memory.usage",
+      metricNativeUnit: "By",
+      legendUnit: "MB",
+      sampleValue: BASELINE_MEAN_MB,
+      nativeUnitsByMetricName: null,
+    });
+
+    expect(anomalyBaseline?.mean).toBe(BASELINE_MEAN);
+    expect(anomalyBaseline?.stddev).toBe(BASELINE_STDDEV);
+  });
+
+  test("the baseline passes through unchanged when the units aren't convertible", async () => {
+    const { anomalyBaseline } = await evaluateAnomaly({
+      metricName: "container.memory.usage",
+      metricNativeUnit: "By",
+      legendUnit: "ms",
+      sampleValue: BASELINE_MEAN,
+    });
+
+    expect(anomalyBaseline?.mean).toBe(BASELINE_MEAN);
+    expect(anomalyBaseline?.stddev).toBe(BASELINE_STDDEV);
+  });
+
+  test("no legendUnit leaves samples and baseline both in the native unit", async () => {
+    const rootCause: string = await anomalyRootCause({
+      metricName: "container.memory.usage",
+      metricNativeUnit: "By",
+      legendUnit: "",
+      sampleValue: BREACHING_VALUE,
+    });
+
+    expect(rootCause).toContain("value 1.07 GB");
+    expect(rootCause).toContain("mean 268 MB");
+    expect(rootCause).toContain("σ 134 MB");
+    expect(rootCause).toContain("is 6.00σ above");
+  });
+});