@worker-manager/metrics 1.0.0 → 1.1.0

package/dist/store.d.ts

@@ -0,0 +1,80 @@
+import type { MetricsClient } from './connection';
+import type { MinutePoint } from './dataMapping';
+import type { HistoryStats, PurgeOptions, PurgeResult } from './HistoryAdmin';
+export interface Retention {
+    /** Days of minute-level detail. Doubles as the recorder's catch-up window. */
+    minutes: number;
+    /** Days of hourly rollup. */
+    hours: number;
+    /** Days of daily totals, which is what the shipped charts read. */
+    days: number;
+}
+export type LatencyMetric = 'runtime' | 'waittime';
+/**
+ * Completed and failed throughput, stored at minute, hour and day resolution per queue plus
+ * the `__global__` rollup.
+ *
+ * Writes are absolute per-minute values, never increments: the minute tier is a ledger, and
+ * each write applies only its difference against what the ledger already holds, to every
+ * coarser tier. Re-writing a minute that is already stored is therefore a no-op, which is what
+ * lets a restarted recorder, or a second one, re-snapshot an overlapping window safely.
+ */
+export interface CounterStore {
+    readonly retention: Retention;
+    upsertMinutes(queue: string, metric: string, points: MinutePoint[]): Promise<void>;
+    /** One entry per requested day: `null` when never recorded, a number (maybe 0) when it was. */
+    readDailyTotals(queue: string, metric: string, days: string[]): Promise<(number | null)[]>;
+    /** Hourly buckets over the given days, keyed by absolute hour index. */
+    readHours(queue: string, metric: string, days: string[]): Promise<Record<string, number>>;
+}
+/**
+ * Latency histograms (runtime, waittime) and the queue-age gauge, at hour and day resolution,
+ * plus the small amount of coordination state the sampler keeps next to them.
+ *
+ * Histograms are merged by increment, so unlike the counters a double write double-counts.
+ * The lease is what prevents that: only its holder scans a queue on a given tick.
+ */
+export interface LatencyStorage {
+    readonly retention: Retention;
+    addSamples(queue: string, metric: LatencyMetric, hour: number, vector: number[]): Promise<void>;
+    recordQueueAge(queue: string, hour: number, ms: number): Promise<void>;
+    /** Keyed by ISO day for `'day'`, by absolute hour index for `'hour'`. */
+    readRange(queue: string, metric: LatencyMetric, granularity: 'hour' | 'day', days: string[]): Promise<Record<string, number[]>>;
+    readQueueAge(queue: string, granularity: 'hour' | 'day', days: string[]): Promise<Record<string, number>>;
+    /** Set-if-absent with a crash-ceiling TTL. `true` when `holder` now owns the queue's lease. */
+    acquireLease(queue: string, holder: string, ttlMs: number): Promise<boolean>;
+    /** Compare and delete: a lease that expired and was retaken by someone else is left alone. */
+    releaseLease(queue: string, holder: string): Promise<void>;
+    /** Finish-time bound of the last scan, epoch ms, or `null` for a cold start. */
+    readWatermark(queue: string): Promise<number | null>;
+    writeWatermark(queue: string, ms: number, ttlSeconds: number): Promise<void>;
+}
+/** Footprint and cleanup, backing the board's storage panel. */
+export interface HistoryAdministration {
+    stats(): Promise<HistoryStats>;
+    purge(options?: PurgeOptions): Promise<PurgeResult>;
+}
+/**
+ * Where recorded history lives. `RedisMetricsStore` and `PostgresMetricsStore` are the two
+ * implementations; hand either to `MetricsRecorder`, a history provider or
+ * `MetricsHistoryAdmin` as `store`.
+ *
+ * The members are the seam those classes are built on rather than an API to call directly.
+ */
+export interface MetricsStore {
+    /** @internal */
+    counterStore(retention: Retention): CounterStore;
+    /** @internal */
+    latencyStore(retention: Retention): LatencyStorage;
+    /** @internal */
+    administration(): HistoryAdministration;
+    /**
+     * @internal
+     * The Redis the sampler reads Redis-backed queues through. A Redis store answers with its
+     * own client, which is the queues' Redis in the classic single-Redis setup; `null` makes the
+     * sampler ask each adapter for its own client instead.
+     */
+    readonly jobClient: MetricsClient | null;
+    /** Releases what the store opened itself. A connection handed in is left to its owner. */
+    close(): Promise<void>;
+}

package/dist/store.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worker-manager/metrics",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Opt-in long-retention historical job metrics recorder and provider for Worker Manager.",
   "keywords": [
     "bull",
@@ -8,6 +8,8 @@
     "dashboard",
     "history",
     "metrics",
+    "postgres",
+    "postgresql",
     "queue",
     "redis"
   ],
@@ -32,22 +34,30 @@
     "test": "jest"
   },
   "dependencies": {
-    "@worker-manager/api": "1.0.0"
+    "@worker-manager/api": "1.1.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
     "@types/node": "^22.20.1",
+    "@types/pg": "^8.23.1",
     "bullmq": "^5.81.3",
     "bullmq-v6": "npm:bullmq@^6",
     "ioredis": "^6.0.0",
     "jest": "^30.4.2",
+    "pg": "^8.23.0",
     "ts-jest": "^29.4.12",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "ioredis": "^5.0.0 || ^6.0.0"
+    "ioredis": "^5.0.0 || ^6.0.0",
+    "pg": "^8.11.0"
   },
   "engines": {
     "node": ">=20"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
   }
 }