@superblocksteam/sdk 2.0.130-next.3 → 2.0.130-next.5

package/src/telemetry/memory-metrics.test.ts

@@ -0,0 +1,363 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import type * as PerfHooks from "node:perf_hooks";
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const h = vi.hoisted(() => {
+  type ObservableInstrument = {
+    name: string;
+    callback?: (result: {
+      observe: (
+        instrument: { name: string },
+        value: number,
+        attrs?: Record<string, unknown>,
+      ) => void;
+    }) => void;
+  };
+
+  const gauges: Array<{
+    name: string;
+    callback?: (result: {
+      observe: (
+        gauge: { name: string },
+        value: number,
+        attrs?: Record<string, unknown>,
+      ) => void;
+    }) => void;
+  }> = [];
+  const observableCounters: ObservableInstrument[] = [];
+  const counters: Array<{
+    name: string;
+    adds: Array<{ value: number; attrs?: Record<string, unknown> }>;
+  }> = [];
+  const histograms: Array<{
+    name: string;
+    options?: Record<string, unknown>;
+    records: Array<{ value: number; attrs?: Record<string, unknown> }>;
+  }> = [];
+
+  return {
+    gauges,
+    observableCounters,
+    counters,
+    histograms,
+    throwOnGaugeName: undefined as string | undefined,
+    delayMonitor: {
+      enable: vi.fn(),
+      disable: vi.fn(),
+      reset: vi.fn(),
+      mean: 2_000_000,
+      max: 80_000_000,
+      percentile: vi.fn((p: number) => p * 1_000_000),
+    },
+    gcCallback: undefined as
+      | ((list: { getEntries: () => unknown[] }) => void)
+      | undefined,
+    elu: vi.fn(),
+    addBatchObservableCallback: vi.fn(
+      (
+        callback: (result: {
+          observe: (
+            gauge: { name: string },
+            value: number,
+            attrs?: Record<string, unknown>,
+          ) => void;
+        }) => void,
+        callbackInstruments: Array<{ name: string }>,
+      ) => {
+        for (const instrument of callbackInstruments) {
+          const captured = [...gauges, ...observableCounters].find(
+            (g) => g.name === instrument.name,
+          );
+          if (captured) captured.callback = callback;
+        }
+      },
+    ),
+    removeBatchObservableCallback: vi.fn(),
+  };
+});
+
+vi.mock("node:perf_hooks", async () => {
+  const actual = await vi.importActual<typeof PerfHooks>("node:perf_hooks");
+  return {
+    ...actual,
+    PerformanceObserver: class {
+      constructor(callback: (list: { getEntries: () => unknown[] }) => void) {
+        h.gcCallback = callback;
+      }
+      observe = vi.fn();
+      disconnect = vi.fn();
+    },
+    monitorEventLoopDelay: vi.fn(() => h.delayMonitor),
+    performance: {
+      ...actual.performance,
+      eventLoopUtilization: h.elu,
+    },
+  };
+});
+
+vi.mock("./index.js", () => ({
+  getMeter: () => ({
+    createObservableGauge: (name: string) => {
+      if (h.throwOnGaugeName === name) {
+        throw new Error(`createObservableGauge failed for ${name}`);
+      }
+      const gauge = { name };
+      h.gauges.push(gauge);
+      return gauge;
+    },
+    createObservableCounter: (name: string) => {
+      const counter = { name };
+      h.observableCounters.push(counter);
+      return counter;
+    },
+    createCounter: (name: string) => {
+      const counter: {
+        name: string;
+        adds: Array<{ value: number; attrs?: Record<string, unknown> }>;
+      } = { name, adds: [] };
+      h.counters.push(counter);
+      return {
+        add: (value: number, attrs?: Record<string, unknown>) =>
+          counter.adds.push({ value, attrs }),
+      };
+    },
+    createHistogram: (name: string, options?: Record<string, unknown>) => {
+      const histogram: {
+        name: string;
+        options?: Record<string, unknown>;
+        records: Array<{ value: number; attrs?: Record<string, unknown> }>;
+      } = { name, options, records: [] };
+      h.histograms.push(histogram);
+      return {
+        record: (value: number, attrs?: Record<string, unknown>) =>
+          histogram.records.push({ value, attrs }),
+      };
+    },
+    addBatchObservableCallback: h.addBatchObservableCallback,
+    removeBatchObservableCallback: h.removeBatchObservableCallback,
+  }),
+}));
+
+function observeAll() {
+  const observations: Array<{
+    name: string;
+    value: number;
+    attrs?: Record<string, unknown>;
+  }> = [];
+  const callback = h.gauges.find((g) => g.callback)?.callback;
+  if (!callback) throw new Error("missing observable callback");
+  callback({
+    observe: (gauge, value, attrs) =>
+      observations.push({ name: gauge.name, value, attrs }),
+  });
+  return observations;
+}
+
+describe("memory metrics", () => {
+  beforeEach(async () => {
+    vi.resetModules();
+    h.gauges.length = 0;
+    h.observableCounters.length = 0;
+    h.counters.length = 0;
+    h.histograms.length = 0;
+    h.throwOnGaugeName = undefined;
+    h.delayMonitor.enable.mockClear();
+    h.delayMonitor.disable.mockClear();
+    h.delayMonitor.reset.mockClear();
+    h.delayMonitor.percentile.mockClear();
+    h.gcCallback = undefined;
+    h.elu.mockReset();
+    h.elu
+      .mockReturnValueOnce({ idle: 0, active: 0, utilization: 0 })
+      .mockReturnValueOnce({ idle: 25, active: 75, utilization: 0.75 })
+      .mockReturnValue({ idle: 100, active: 200, utilization: 0.67 });
+    h.addBatchObservableCallback.mockClear();
+    h.removeBatchObservableCallback.mockClear();
+  });
+
+  it("observes event-loop, V8 heap, and memory-pressure gauges", async () => {
+    const { startMemoryMetrics, stopMemoryMetrics } =
+      await import("./memory-metrics.js");
+
+    startMemoryMetrics();
+    const observations = observeAll();
+    stopMemoryMetrics();
+
+    expect(h.delayMonitor.enable).toHaveBeenCalledOnce();
+    expect(observations.map((o) => o.name)).toEqual(
+      expect.arrayContaining([
+        "nodejs.event_loop.delay.max_ms",
+        "nodejs.event_loop.delay.p99_ms",
+        "nodejs.event_loop.utilization",
+        "nodejs.memory.heap_limit_bytes",
+        "nodejs.memory.heap_used_ratio",
+      ]),
+    );
+    expect(h.observableCounters.map((counter) => counter.name)).toEqual([
+      "nodejs.process.cpu.user_seconds",
+      "nodejs.process.cpu.system_seconds",
+    ]);
+    expect(
+      observations.find((o) => o.name === "nodejs.event_loop.delay.max_ms")
+        ?.value,
+    ).toBe(80);
+    expect(
+      observations.find((o) => o.name === "nodejs.event_loop.utilization")
+        ?.value,
+    ).toBe(0.75);
+    expect(h.delayMonitor.reset).toHaveBeenCalledOnce();
+    expect(h.delayMonitor.disable).toHaveBeenCalledOnce();
+  });
+
+  it("cleans up the event-loop delay monitor when setup fails", async () => {
+    const { startMemoryMetrics, stopMemoryMetrics } =
+      await import("./memory-metrics.js");
+
+    h.throwOnGaugeName = "nodejs.memory.rss_bytes";
+    expect(() => startMemoryMetrics()).toThrow(
+      "createObservableGauge failed for nodejs.memory.rss_bytes",
+    );
+    expect(h.delayMonitor.disable).toHaveBeenCalledOnce();
+
+    h.throwOnGaugeName = undefined;
+    startMemoryMetrics();
+    stopMemoryMetrics();
+
+    expect(h.delayMonitor.enable).toHaveBeenCalledOnce();
+    expect(h.delayMonitor.disable).toHaveBeenCalledTimes(2);
+  });
+
+  it("resets event-loop delay even when observation fails", async () => {
+    const { startMemoryMetrics, stopMemoryMetrics } =
+      await import("./memory-metrics.js");
+
+    startMemoryMetrics();
+    const callback = h.gauges.find((g) => g.callback)?.callback;
+    if (!callback) throw new Error("missing observable callback");
+
+    expect(() =>
+      callback({
+        observe: (instrument) => {
+          if (instrument.name === "nodejs.memory.rss_bytes") {
+            throw new Error("observe failed");
+          }
+        },
+      }),
+    ).toThrow("observe failed");
+
+    stopMemoryMetrics();
+    expect(h.delayMonitor.reset).toHaveBeenCalledOnce();
+  });
+
+  it("does not register metrics twice until stopped", async () => {
+    const { startMemoryMetrics, stopMemoryMetrics } =
+      await import("./memory-metrics.js");
+
+    startMemoryMetrics();
+    startMemoryMetrics();
+    stopMemoryMetrics();
+    startMemoryMetrics();
+    stopMemoryMetrics();
+
+    expect(h.delayMonitor.enable).toHaveBeenCalledTimes(2);
+    expect(h.addBatchObservableCallback).toHaveBeenCalledTimes(2);
+    expect(h.removeBatchObservableCallback).toHaveBeenCalledTimes(2);
+  });
+
+  it("records GC count and duration with bounded kind labels", async () => {
+    const { startMemoryMetrics, stopMemoryMetrics } =
+      await import("./memory-metrics.js");
+
+    startMemoryMetrics();
+    h.gcCallback?.({
+      getEntries: () => [
+        { detail: { kind: 1 }, duration: 12 },
+        { detail: { kind: 4 }, duration: 34 },
+        { kind: 999, duration: 56 },
+      ],
+    });
+    stopMemoryMetrics();
+
+    const gcCounter = h.counters.find((c) => c.name === "nodejs.gc.count");
+    const gcDuration = h.histograms.find(
+      (histogram) => histogram.name === "nodejs.gc.duration_ms",
+    );
+
+    expect(gcCounter?.adds.map((a) => a.attrs)).toEqual([
+      { kind: "minor" },
+      { kind: "major" },
+      { kind: "unknown" },
+    ]);
+    expect(gcDuration?.records).toEqual([
+      { value: 12, attrs: { kind: "minor" } },
+      { value: 34, attrs: { kind: "major" } },
+      { value: 56, attrs: { kind: "unknown" } },
+    ]);
+    expect(gcDuration?.options).toEqual({
+      description: "Garbage collection duration by collection kind",
+      unit: "ms",
+      advice: {
+        explicitBucketBoundaries: [0.5, 1, 2, 5, 10, 25, 50, 100, 250, 500],
+      },
+    });
+  });
+});
+
+describe("readCgroupMemory", () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  it("reads cgroup v2 memory usage and ratio", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "sb-cgroup-"));
+    writeFileSync(path.join(root, "memory.current"), "50\n");
+    writeFileSync(path.join(root, "memory.max"), "200\n");
+    const { readCgroupMemory } = await import("./memory-metrics.js");
+
+    expect(readCgroupMemory(root)).toEqual({
+      currentBytes: 50,
+      limitBytes: 200,
+      usageRatio: 0.25,
+    });
+  });
+
+  it("returns undefined when cgroup files are absent or unlimited", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "sb-cgroup-"));
+    const { readCgroupMemory } = await import("./memory-metrics.js");
+
+    expect(readCgroupMemory(root)).toBeUndefined();
+    writeFileSync(path.join(root, "memory.current"), "50\n");
+    writeFileSync(path.join(root, "memory.max"), "max\n");
+    expect(readCgroupMemory(root)).toBeUndefined();
+  });
+
+  it("does not combine v2 usage with v1 limits", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "sb-cgroup-"));
+    const memoryRoot = path.join(root, "memory");
+    mkdirSync(memoryRoot);
+    writeFileSync(path.join(root, "memory.current"), "50\n");
+    writeFileSync(path.join(root, "memory.max"), "max\n");
+    writeFileSync(path.join(memoryRoot, "memory.usage_in_bytes"), "60\n");
+    writeFileSync(path.join(memoryRoot, "memory.limit_in_bytes"), "200\n");
+    const { readCgroupMemory } = await import("./memory-metrics.js");
+
+    expect(readCgroupMemory(root)).toBeUndefined();
+  });
+
+  it("treats cgroup v1 sentinel limits as unlimited", async () => {
+    const root = mkdtempSync(path.join(tmpdir(), "sb-cgroup-"));
+    const memoryRoot = path.join(root, "memory");
+    mkdirSync(memoryRoot);
+    writeFileSync(path.join(memoryRoot, "memory.usage_in_bytes"), "50\n");
+    writeFileSync(
+      path.join(memoryRoot, "memory.limit_in_bytes"),
+      "9223372036854771712\n",
+    );
+    const { readCgroupMemory } = await import("./memory-metrics.js");
+
+    expect(readCgroupMemory(root)).toBeUndefined();
+  });
+});