@oneuptime/common 12.0.5 → 12.0.7

package/Tests/Utils/Telemetry/CaptureSpanExportGating.test.ts

@@ -0,0 +1,288 @@
+import { describe, expect, jest, test, beforeEach } from "@jest/globals";
+
+/*
+ * Contract under test — @CaptureSpan's export gating.
+ *
+ * The decorator wraps ~hundreds of methods, some of which sit on per-record
+ * telemetry ingest paths. It must be a plain method call (no span, no
+ * attribute flattening, no AsyncLocalStorage transition) whenever no span
+ * exporter is installed — spans that are never exported are pure overhead —
+ * and only build the attribute object when there is actually something to
+ * attach. When an exporter IS installed it must keep the full original
+ * behavior: named span, OK status on success, recorded exception + rethrow
+ * on failure, for both sync and async methods.
+ */
+
+type JestMock = ReturnType<typeof jest.fn>;
+
+type FakeSpan = {
+  setStatus: JestMock;
+  end: JestMock;
+};
+
+const fakeSpan: FakeSpan = {
+  setStatus: jest.fn(),
+  end: jest.fn(),
+};
+
+let spanExportEnabled: boolean = false;
+
+const startActiveSpanMock: JestMock = jest.fn((data: any) => {
+  return data.fn(fakeSpan);
+});
+const recordExceptionMock: JestMock = jest.fn();
+
+jest.mock("../../../Server/Utils/Telemetry", () => {
+  return {
+    __esModule: true,
+    default: {
+      isSpanExportEnabled: (): boolean => {
+        return spanExportEnabled;
+      },
+      startActiveSpan: (data: unknown): unknown => {
+        return startActiveSpanMock(data);
+      },
+      recordExceptionMarkSpanAsErrorAndEndSpan: (data: unknown): unknown => {
+        return recordExceptionMock(data);
+      },
+    },
+  };
+});
+
+jest.mock("../../../Server/EnvironmentConfig", () => {
+  const actual: Record<string, unknown> = jest.requireActual(
+    "../../../Server/EnvironmentConfig",
+  ) as Record<string, unknown>;
+  return {
+    ...actual,
+    DisableTelemetry: false,
+  };
+});
+
+import CaptureSpan from "../../../Server/Utils/Telemetry/CaptureSpan";
+
+/*
+ * Apply the decorator exactly the way TypeScript does for a static method,
+ * without relying on decorator syntax support in the test transform.
+ */
+function decorate(
+  data: Parameters<typeof CaptureSpan>[0] | undefined,
+  fn: (...args: Array<any>) => any,
+  methodName: string = "method",
+): (...args: Array<any>) => any {
+  class Host {}
+  const descriptor: TypedPropertyDescriptor<any> = { value: fn };
+  CaptureSpan(data)(Host, methodName, descriptor);
+  return descriptor.value;
+}
+
+beforeEach(() => {
+  spanExportEnabled = false;
+  startActiveSpanMock.mockClear();
+  recordExceptionMock.mockClear();
+  fakeSpan.setStatus.mockClear();
+  fakeSpan.end.mockClear();
+});
+
+describe("CaptureSpan with no span exporter installed", () => {
+  test("calls the original method directly and creates no span", () => {
+    const original: JestMock = jest.fn().mockReturnValue("result");
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, original);
+
+    expect(wrapped("a", 1)).toBe("result");
+    expect(original).toHaveBeenCalledWith("a", 1);
+    expect(startActiveSpanMock).not.toHaveBeenCalled();
+  });
+
+  test("preserves `this` binding", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      undefined,
+      function (this: { value: number }): number {
+        return this.value;
+      },
+    );
+
+    expect(wrapped.call({ value: 42 })).toBe(42);
+  });
+
+  test("async results and rejections pass through untouched", async () => {
+    const wrappedOk: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<string> => {
+        return "async-result";
+      },
+    );
+    await expect(wrappedOk()).resolves.toBe("async-result");
+
+    const boom: Error = new Error("boom");
+    const wrappedFail: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<never> => {
+        throw boom;
+      },
+    );
+    await expect(wrappedFail()).rejects.toBe(boom);
+    expect(startActiveSpanMock).not.toHaveBeenCalled();
+  });
+
+  test("sync throws pass through untouched", () => {
+    const boom: Error = new Error("sync-boom");
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      throw boom;
+    });
+
+    expect(() => {
+      return wrapped();
+    }).toThrow(boom);
+    expect(startActiveSpanMock).not.toHaveBeenCalled();
+  });
+});
+
+describe("CaptureSpan with a span exporter installed", () => {
+  beforeEach(() => {
+    spanExportEnabled = true;
+  });
+
+  test("creates a span named Class.method and returns the result", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      undefined,
+      () => {
+        return "spanned";
+      },
+      "doWork",
+    );
+
+    expect(wrapped()).toBe("spanned");
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(1);
+
+    const callData: any = startActiveSpanMock.mock.calls[0]![0];
+    expect(callData.name).toBe("Host.doWork");
+    expect(fakeSpan.setStatus).toHaveBeenCalledWith({ code: 1 }); // OK
+    expect(fakeSpan.end).toHaveBeenCalledTimes(1);
+  });
+
+  test("bare @CaptureSpan() attaches no attributes (flattening skipped)", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "x";
+    });
+    wrapped("argument-that-must-not-be-captured");
+
+    const callData: any = startActiveSpanMock.mock.calls[0]![0];
+    expect(callData.options).toEqual({});
+  });
+
+  test("captureArguments flattens call arguments into span attributes", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      { captureArguments: true },
+      () => {
+        return "x";
+      },
+    );
+    wrapped("first", { nested: { key: "v" } });
+
+    const callData: any = startActiveSpanMock.mock.calls[0]![0];
+    expect(callData.options.attributes["arg0"]).toBe("first");
+    expect(callData.options.attributes["arg1.nested.key"]).toBe("v");
+  });
+
+  test("static attributes are attached", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      { attributes: { component: "test" } },
+      () => {
+        return "x";
+      },
+    );
+    wrapped();
+
+    const callData: any = startActiveSpanMock.mock.calls[0]![0];
+    expect(callData.options.attributes["component"]).toBe("test");
+  });
+
+  test("async success marks the span OK and ends it", async () => {
+    const wrapped: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<string> => {
+        return "ok";
+      },
+    );
+
+    await expect(wrapped()).resolves.toBe("ok");
+    expect(fakeSpan.setStatus).toHaveBeenCalledWith({ code: 1 });
+    expect(fakeSpan.end).toHaveBeenCalledTimes(1);
+  });
+
+  test("async failure records the exception, rethrows, and ends the span", async () => {
+    const boom: Error = new Error("async-span-boom");
+    const wrapped: (...args: Array<any>) => any = decorate(
+      undefined,
+      async (): Promise<never> => {
+        throw boom;
+      },
+    );
+
+    await expect(wrapped()).rejects.toBe(boom);
+    expect(recordExceptionMock).toHaveBeenCalledTimes(1);
+    expect(recordExceptionMock.mock.calls[0]![0]).toMatchObject({
+      exception: boom,
+    });
+    expect(fakeSpan.end).toHaveBeenCalledTimes(1);
+  });
+
+  test("sync failure records the exception and rethrows", () => {
+    const boom: Error = new Error("sync-span-boom");
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      throw boom;
+    });
+
+    expect(() => {
+      return wrapped();
+    }).toThrow(boom);
+    expect(recordExceptionMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("export flag is consulted at call time, not decoration time", () => {
+  /*
+   * Decorators run at class-definition (import) time, long before
+   * Telemetry.init() installs an exporter and flips the flag. If the wrapper
+   * captured the flag when it was applied instead of reading it per call,
+   * every span in the process would be silently lost — decoration always
+   * happens while the flag is still false.
+   */
+  test("a method decorated before the exporter exists starts spanning once export turns on", () => {
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "x";
+    });
+
+    expect(wrapped()).toBe("x");
+    expect(startActiveSpanMock).not.toHaveBeenCalled();
+
+    spanExportEnabled = true;
+    expect(wrapped()).toBe("x");
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("a method decorated while export was on drops to passthrough when it turns off", () => {
+    spanExportEnabled = true;
+    const wrapped: (...args: Array<any>) => any = decorate(undefined, () => {
+      return "y";
+    });
+
+    expect(wrapped()).toBe("y");
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(1);
+
+    spanExportEnabled = false;
+    expect(wrapped()).toBe("y");
+    expect(startActiveSpanMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("Telemetry.isSpanExportEnabled (real module)", () => {
+  test("defaults to false before init installs a trace exporter", () => {
+    const RealTelemetry: any = (
+      jest.requireActual("../../../Server/Utils/Telemetry") as any
+    ).default;
+
+    expect(RealTelemetry.isSpanExportEnabled()).toBe(false);
+  });
+});

package/Tests/Utils/Telemetry/IngestionTimestamp.test.ts

@@ -0,0 +1,170 @@
+import {
+  IngestionStamp,
+  getIngestionStamp,
+  getRetentionDateDb,
+} from "../../../Server/Utils/Telemetry/IngestionTimestamp";
+import OneUptimeDate from "../../../Types/Date";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  jest,
+  test,
+} from "@jest/globals";
+
+/*
+ * Minimal structural view of a jest spy — the @jest/globals and @types/jest
+ * spy types disagree in this repo, so annotate with just the surface this
+ * test reads.
+ */
+type SpyLike = {
+  mock: { calls: Array<Array<unknown>> };
+  mockRestore: () => void;
+};
+
+/*
+ * Contract under test — the per-second memo behind every ingested row's
+ * createdAt / retentionDate stamps.
+ *
+ * The Otel logs / traces / metrics row builders used to derive these per
+ * row (current Date + ClickHouse format + moment add-days + second format,
+ * per log record / span / metric datapoint). The memo must hand out values
+ * IDENTICAL to that per-row derivation — same second → same strings — and
+ * roll over crisply on the second boundary, or rows would carry stale
+ * createdAt / retention stamps.
+ */
+
+describe("getIngestionStamp", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  test("db string matches toClickhouseDateTime of the stamp's date", () => {
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.700Z"));
+
+    const stamp: IngestionStamp = getIngestionStamp();
+
+    expect(stamp.db).toBe(OneUptimeDate.toClickhouseDateTime(stamp.date));
+    expect(stamp.db).toBe("2026-08-10 13:45:59");
+  });
+
+  test("date is truncated to the second", () => {
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.999Z"));
+
+    const stamp: IngestionStamp = getIngestionStamp();
+
+    expect(stamp.date.getMilliseconds()).toBe(0);
+    expect(stamp.date.getTime()).toBe(
+      new Date("2026-08-10T13:45:59.000Z").getTime(),
+    );
+  });
+
+  test("same second returns the identical stamp object (memo hit)", () => {
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.100Z"));
+    const first: IngestionStamp = getIngestionStamp();
+
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.900Z"));
+    const second: IngestionStamp = getIngestionStamp();
+
+    expect(second).toBe(first);
+  });
+
+  test("rolls over when the second changes", () => {
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.900Z"));
+    const first: IngestionStamp = getIngestionStamp();
+
+    jest.setSystemTime(new Date("2026-08-10T13:46:00.000Z"));
+    const second: IngestionStamp = getIngestionStamp();
+
+    expect(second).not.toBe(first);
+    expect(first.db).toBe("2026-08-10 13:45:59");
+    expect(second.db).toBe("2026-08-10 13:46:00");
+  });
+});
+
+describe("getRetentionDateDb", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.setSystemTime(new Date("2026-08-10T13:45:59.700Z"));
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  test("equals the per-row derivation it replaced (addRemoveDays + format)", () => {
+    const stamp: IngestionStamp = getIngestionStamp();
+
+    for (const days of [1, 15, 30, 90, 365]) {
+      expect(getRetentionDateDb(stamp, days)).toBe(
+        OneUptimeDate.toClickhouseDateTime(
+          OneUptimeDate.addRemoveDays(stamp.date, days),
+        ),
+      );
+    }
+  });
+
+  test("distinct retention windows produce distinct dates", () => {
+    const stamp: IngestionStamp = getIngestionStamp();
+
+    expect(getRetentionDateDb(stamp, 15)).toBe(
+      OneUptimeDate.toClickhouseDateTime(
+        OneUptimeDate.addRemoveDays(stamp.date, 15),
+      ),
+    );
+    expect(getRetentionDateDb(stamp, 30)).toBe(
+      OneUptimeDate.toClickhouseDateTime(
+        OneUptimeDate.addRemoveDays(stamp.date, 30),
+      ),
+    );
+    expect(getRetentionDateDb(stamp, 15)).not.toBe(
+      getRetentionDateDb(stamp, 30),
+    );
+  });
+
+  test("memoizes per retention window: addRemoveDays runs once per (second, days)", () => {
+    const stamp: IngestionStamp = getIngestionStamp();
+    const addRemoveDaysSpy: SpyLike = jest.spyOn(
+      OneUptimeDate,
+      "addRemoveDays",
+    ) as unknown as SpyLike;
+
+    const first: string = getRetentionDateDb(stamp, 15);
+    const callsAfterFirst: number = addRemoveDaysSpy.mock.calls.length;
+
+    for (let i: number = 0; i < 50; i++) {
+      expect(getRetentionDateDb(stamp, 15)).toBe(first);
+    }
+
+    expect(addRemoveDaysSpy.mock.calls.length).toBe(callsAfterFirst);
+    addRemoveDaysSpy.mockRestore();
+  });
+
+  test("stays consistent with the stamp's own second, not the current clock", () => {
+    const stamp: IngestionStamp = getIngestionStamp();
+    const expected: string = getRetentionDateDb(stamp, 15);
+
+    // Clock moves on; a held stamp must keep answering for ITS second.
+    jest.setSystemTime(new Date("2026-08-10T13:46:30.000Z"));
+
+    expect(getRetentionDateDb(stamp, 15)).toBe(expected);
+  });
+
+  test("computes correctly for a bare stamp that never went through the memo", () => {
+    const bareStamp: IngestionStamp = {
+      date: new Date("2026-01-01T00:00:00.000Z"),
+      db: "2026-01-01 00:00:00",
+    };
+
+    expect(getRetentionDateDb(bareStamp, 15)).toBe(
+      OneUptimeDate.toClickhouseDateTime(
+        OneUptimeDate.addRemoveDays(bareStamp.date, 15),
+      ),
+    );
+  });
+});

package/Tests/Utils/Telemetry/SavedViewFilters.test.ts

@@ -0,0 +1,246 @@
+import JSONFunctions from "../../../Types/JSONFunctions";
+import TelemetrySavedViewState from "../../../Types/Telemetry/TelemetrySavedViewState";
+import { JSONObject } from "../../../Types/JSON";
+import {
+  readSavedViewFilters,
+  SavedViewFilterTuple,
+} from "../../../Utils/Telemetry/SavedViewFilters";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * Facet filters are stored as [facetKey, value] tuples inside a JSON column,
+ * and for a while the serializer rewrote every one of them into
+ * { "0": facetKey, "1": value }. Those rows are still in the database, so the
+ * explorers cannot destructure saved filters directly — a single bad row used
+ * to take the whole Traces page down with
+ * "TypeError: (destructured parameter) is not iterable".
+ *
+ * These tests cover both shapes and the junk in between.
+ */
+
+// The shape a pre-fix serializer left in the database.
+const LEGACY_CORRUPTED_FILTERS: unknown = [
+  { "0": "primaryEntityId", "1": "6512f1a0a1b2c3d4e5f60718" },
+  { "0": "attributes.http.method", "1": "GET" },
+];
+
+describe("readSavedViewFilters", () => {
+  describe("Well-formed saved state", () => {
+    test("Reads tuples that were stored correctly", () => {
+      expect(
+        readSavedViewFilters([
+          ["service", "api"],
+          ["status", "error"],
+        ]),
+      ).toEqual([
+        ["service", "api"],
+        ["status", "error"],
+      ]);
+    });
+
+    test("Reads a single tuple", () => {
+      expect(readSavedViewFilters([["service", "api"]])).toEqual([
+        ["service", "api"],
+      ]);
+    });
+
+    test("Returns an empty list for an empty list", () => {
+      expect(readSavedViewFilters([])).toEqual([]);
+    });
+
+    test("Keeps a filter whose value is deliberately the empty string", () => {
+      expect(readSavedViewFilters([["statusMessage", ""]])).toEqual([
+        ["statusMessage", ""],
+      ]);
+    });
+
+    test("Ignores anything beyond the first two elements of a tuple", () => {
+      expect(
+        readSavedViewFilters([["service", "api", "extra", "junk"]]),
+      ).toEqual([["service", "api"]]);
+    });
+
+    test("Preserves order", () => {
+      expect(
+        readSavedViewFilters([
+          ["c", "3"],
+          ["a", "1"],
+          ["b", "2"],
+        ]),
+      ).toEqual([
+        ["c", "3"],
+        ["a", "1"],
+        ["b", "2"],
+      ]);
+    });
+
+    test("Returns real arrays, so callers can destructure them", () => {
+      const filters: Array<SavedViewFilterTuple> = readSavedViewFilters([
+        ["service", "api"],
+      ]);
+
+      const read: Array<string> = filters.map(
+        ([facetKey, value]: SavedViewFilterTuple): string => {
+          return `${facetKey}:${value}`;
+        },
+      );
+
+      expect(read).toEqual(["service:api"]);
+    });
+  });
+
+  describe("Legacy rows corrupted by the old serializer", () => {
+    test("Reads { '0': key, '1': value } back into a tuple", () => {
+      expect(readSavedViewFilters(LEGACY_CORRUPTED_FILTERS)).toEqual([
+        ["primaryEntityId", "6512f1a0a1b2c3d4e5f60718"],
+        ["attributes.http.method", "GET"],
+      ]);
+    });
+
+    test("A healed legacy row is destructurable", () => {
+      const filters: Array<SavedViewFilterTuple> = readSavedViewFilters(
+        LEGACY_CORRUPTED_FILTERS,
+      );
+
+      expect(() => {
+        return filters.map(([facetKey]: SavedViewFilterTuple): string => {
+          return facetKey;
+        });
+      }).not.toThrow();
+    });
+
+    test("Reads a list that mixes healed and correct rows", () => {
+      expect(
+        readSavedViewFilters([
+          { "0": "service", "1": "api" },
+          ["status", "error"],
+        ]),
+      ).toEqual([
+        ["service", "api"],
+        ["status", "error"],
+      ]);
+    });
+
+    test("Heals exactly what the old serializer produced, end to end", () => {
+      /*
+       * Reproduce the corruption the way it actually happened — through the
+       * pre-fix serializer — rather than hand-writing the broken shape.
+       */
+      const corrupted: JSONObject = {
+        filters: [
+          { "0": "service", "1": "api" },
+          { "0": "status", "1": "error" },
+        ],
+      };
+
+      expect(readSavedViewFilters(corrupted["filters"])).toEqual([
+        ["service", "api"],
+        ["status", "error"],
+      ]);
+    });
+  });
+
+  describe("Malformed saved state never throws", () => {
+    test("Returns an empty list for undefined, null and non-arrays", () => {
+      expect(readSavedViewFilters(undefined)).toEqual([]);
+      expect(readSavedViewFilters(null)).toEqual([]);
+      expect(readSavedViewFilters("service:api")).toEqual([]);
+      expect(readSavedViewFilters(42)).toEqual([]);
+      expect(readSavedViewFilters(true)).toEqual([]);
+      expect(readSavedViewFilters({})).toEqual([]);
+      expect(readSavedViewFilters({ service: "api" })).toEqual([]);
+    });
+
+    test("Drops entries that are not tuple-shaped at all", () => {
+      expect(
+        readSavedViewFilters([
+          "service:api",
+          42,
+          null,
+          undefined,
+          true,
+          ["status", "error"],
+        ]),
+      ).toEqual([["status", "error"]]);
+    });
+
+    test("Drops entries with no usable facet key", () => {
+      expect(
+        readSavedViewFilters([
+          [],
+          ["", "api"],
+          [null, "api"],
+          [{ nested: true }, "api"],
+          ["service", "api"],
+        ]),
+      ).toEqual([["service", "api"]]);
+    });
+
+    test("Falls back to an empty value when the stored value is unusable", () => {
+      expect(readSavedViewFilters([["service", null]])).toEqual([
+        ["service", ""],
+      ]);
+      expect(readSavedViewFilters([["service"]])).toEqual([["service", ""]]);
+      expect(readSavedViewFilters([["service", { nested: true }]])).toEqual([
+        ["service", ""],
+      ]);
+      expect(readSavedViewFilters([["service", ["a"]]])).toEqual([
+        ["service", ""],
+      ]);
+    });
+
+    test("Stringifies values that came back as numbers or booleans", () => {
+      expect(
+        readSavedViewFilters([
+          ["duration", 500],
+          ["hasException", true],
+        ]),
+      ).toEqual([
+        ["duration", "500"],
+        ["hasException", "true"],
+      ]);
+    });
+
+    test("Drops non-finite numeric values rather than writing 'NaN' into a chip", () => {
+      expect(readSavedViewFilters([["duration", NaN]])).toEqual([
+        ["duration", ""],
+      ]);
+      expect(readSavedViewFilters([["duration", Infinity]])).toEqual([
+        ["duration", ""],
+      ]);
+    });
+
+    test("Reads a numeric facet key stored as a number", () => {
+      expect(readSavedViewFilters([[7, "api"]])).toEqual([["7", "api"]]);
+    });
+  });
+
+  describe("Round trip through the serializer that stores the view", () => {
+    test("Filters written by the fixed serializer read straight back", () => {
+      const state: TelemetrySavedViewState = {
+        search: "status:error",
+        filters: [
+          ["service", "api"],
+          ["attributes.http.method", "GET"],
+        ],
+        pageSize: 50,
+      };
+
+      const stored: JSONObject = JSONFunctions.deserialize(
+        JSON.parse(
+          JSON.stringify(JSONFunctions.serialize(state as JSONObject)),
+        ),
+      );
+
+      expect(readSavedViewFilters(stored["filters"])).toEqual(state.filters);
+    });
+
+    test("A view with no filters at all reads as no filters", () => {
+      const state: TelemetrySavedViewState = { search: "status:error" };
+
+      const stored: JSONObject = JSONFunctions.serialize(state as JSONObject);
+
+      expect(readSavedViewFilters(stored["filters"])).toEqual([]);
+    });
+  });
+});