@worker-manager/metrics 1.0.1 → 1.1.0

package/README.md

@@ -1,10 +1,11 @@
 # @worker-manager/metrics
 
-> Status: Beta. The API and Redis storage layout may still change in a minor release while the feature settles. It is safe to run (opt-in, and it only writes its own namespaced keys), but pin an exact version if you depend on the storage format.
+> Status: Beta. The API and the Redis and PostgreSQL storage layouts may still change in a minor release while the feature settles. It is safe to run (opt-in, and it only writes its own namespaced keys), but pin an exact version if you depend on the storage format.
 
 Opt-in long-retention historical job metrics for [Worker Manager](https://github.com/naldomadeira/worker-manager).
 
-Snapshots native BullMQ per-minute metrics into long-retention Redis buckets and exposes a
+Snapshots native BullMQ per-minute metrics into long-retention buckets, in Redis or in
+PostgreSQL (see [PostgreSQL storage](#postgresql-storage)), and exposes a
 `MetricsHistoryProvider` that feeds bull-board's history charts. Everything is opt-in: the core
 `@worker-manager/api` stays stateless.
 
@@ -74,7 +75,7 @@ The CLI and the Docker image reach a cluster with `--cluster`, where `--history`
 
 Alongside the completed/failed counters, the recorder tracks two histograms per queue: wait time (`processedOn - timestamp`, how long a job sat before a worker picked it up) and run time (`finishedOn - processedOn`, how long the handler took). They diagnose different problems, so they're kept separate rather than combined into one number.
 
-Both are collected by scanning the completed and failed sorted sets (BullMQ scores them by finish time via `moveToFinished`'s `ZADD`) past a watermark on the recorder's existing tick, so no worker changes are needed and there's no precondition on `queue.getMetrics()`.
+Both are collected by scanning the completed and failed sorted sets (BullMQ scores them by finish time via `moveToFinished`'s `ZADD`), or the `job` table of a PostgreSQL-backed queue, past a watermark on the recorder's existing tick, so no worker changes are needed and there's no precondition on `queue.getMetrics()`.
 
 The wait histogram only sees jobs that finished, so it goes quiet exactly when a queue is backed up and jobs stop finishing. A queue-age gauge (oldest job still waiting) is recorded alongside it for that reason, and the UI overlays it on the wait chart. Retries are excluded from wait time only, since `timestamp` is a job's creation but `processedOn` is its latest attempt. Percentiles are estimates bounded by bucket width; the bucket layout is fixed, not configurable, because two ranges with different layouts can't be merged into one percentile.
 
@@ -82,10 +83,88 @@ The wait histogram only sees jobs that finished, so it goes quiet exactly when a
 
 ## PostgreSQL-backed queues
 
-A BullMQ 6 queue backed by PostgreSQL records no history. Its `getMetrics()` reports `prevTS` as 0, which leaves the per-minute buffer undatable, so the counters are dropped rather than dated from the recorder's clock; the field is tracked in the backend's schema, so this may resolve upstream. Latency sampling needs BullMQ's Redis keys, which such a queue does not have, so it is skipped rather than recorded as an empty backlog. Redis-backed queues on the same board are unaffected.
+A BullMQ 6 queue backed by PostgreSQL is recorded like any other. Its counters come from `getMetrics()`, whose per-minute buffer the adapter anchors from BullMQ's `metrics` table (BullMQ's own PostgreSQL `getMetrics()` reports `prevTS` as 0). Latency and queue age are read from BullMQ's `job` table through the queue's own pool: finished jobs by `(queue, state, finished_at_ms)`, which BullMQ indexes, and the backlog from three index probes on the ready index rather than a scan. Paused and prioritized jobs are ordinary `waiting` rows there, so both count towards the backlog, as they do on Redis.
+
+Where a queue lives and where its history is stored are independent: PostgreSQL queues can record into Redis next to Redis queues, and the reverse works too. A board with no Redis at all stores its history in PostgreSQL, below.
+
+## PostgreSQL storage
+
+For deployments that run BullMQ 6 entirely on PostgreSQL, the history can live there too. Same tiers, retention, `__global__` rollup, latency histograms and queue-age gauge as the Redis store, behind the same `MetricsHistoryProvider` contract, so the board, its charts and its storage panel cannot tell the two apart.
+
+`pg` is an optional peer dependency: install it (`npm install pg`) only for this. Redis-only installs never load it.
+
+    import {
+      MetricsRecorder,
+      PostgresMetricsHistoryProvider,
+      PostgresMetricsStore,
+    } from '@worker-manager/metrics';
+
+    const store = new PostgresMetricsStore({
+      connection: process.env.DATABASE_URL, // or a pg.Pool, or a pool config
+      schema: 'bullmq',                      // default: `schema` of a pool config, then `public`
+      migrate: true,                         // create or upgrade the tables on first use
+    });
+
+    const recorder = new MetricsRecorder({ queues, store, retentionDays: 90 });
+    recorder.start();
+
+    createBullBoard({
+      queues,
+      serverAdapter,
+      options: { historyProvider: new PostgresMetricsHistoryProvider({ store, retentionDays: 90 }) },
+    });
+
+    // On shutdown: recorder.stop(), then await store.close().
+
+`connection` takes what BullMQ's PostgreSQL backend takes: a `pg.Pool` (left open by `close()`), a node-postgres pool config, or a connection string (both of which get a pool that `close()` ends). A `schema` key in a pool config is honoured, so the object you hand BullMQ can be reused as is. The provider also accepts `{ connection, schema, tablePrefix, migrate }` directly and then owns its store (`await provider.disconnect()`). `MetricsHistoryAdmin` takes `{ store }` the same way.
+
+A store only writes; the queues it records are whatever the recorder is given, on any datastore. Pass `onSnapshotError` to the recorder to see a tick that failed because the database was unreachable; the next tick retries.
+
+### Schema and migrations
+
+Four tables, named `<tablePrefix><name>` (`tablePrefix` defaults to `bull_board_metrics_`) in `schema`:
+
+| Table | Key | Holds |
+| --- | --- | --- |
+| `counters` | `(queue, metric, tier, bucket)` | completed/failed sums at minute, hour and day resolution; the queue-age max at hour and day |
+| `histograms` | `(queue, metric, tier, bucket)` | runtime/waittime bucket counts, a `bigint[]` of the 18 fixed bounds, at hour and day |
+| `sampler_state` | `(queue, kind)` | the sampler's lease and finish-time watermark, with an expiry |
+| `meta` | `name` | `schema_version` |
+
+`bucket` is an absolute minute, hour or day index since the epoch, UTC; `queue = '__global__'` is the cross-queue rollup. `counters` and `histograms` carry a `(tier, bucket)` index for retention.
+
+`migrate: true` creates the schema (only when it is missing, so no database-level `CREATE` privilege is needed when it exists) and the tables on first use, in one transaction behind an advisory lock, so several processes can start at once. Without it the first query checks `schema_version` and fails with instructions if the tables are missing. Where the application role has no DDL rights, migrate from a deploy step instead:
+
+    import { migratePostgresMetrics } from '@worker-manager/metrics';
+    await migratePostgresMetrics({ connection: process.env.DATABASE_URL, schema: 'bullmq' });
+
+Migrations are versioned and append-only; a database newer than the installed package is refused rather than written to. Two boards can share a database by `schema` or `tablePrefix`, the equivalent of the Redis `prefix`.
+
+### Idempotency and concurrency
+
+Each snapshot of a queue's metric is one transaction: a transaction-scoped advisory lock on (tables, queue, metric), then one statement that diffs the incoming minutes against the minute rows and applies only the differences to the hour and day rows of the queue and of `__global__` (`INSERT ... ON CONFLICT DO UPDATE SET value = value + delta`). Re-snapshotting an overlapping window after a restart, or from a second recorder, applies a delta of zero, exactly like the Redis `EVAL`. Histograms merge element-wise and the queue-age gauge keeps `GREATEST`, in one multi-row upsert each. The sampler's lease is an upsert that only overwrites an expired row, on the database clock, so two recorders never both scan a queue on the same tick.
+
+### Retention
+
+The same per-tier windows as Redis. Instead of TTLs, each writer deletes the rows older than each tier's window on its first write and then once per new UTC day, anchored on the day being written, which is how the Redis scripts trim the totals hashes. Expired sampler state goes at the same time. Deleted rows are reclaimed by autovacuum as usual.
+
+### Sizing
+
+Every bucket is its own row, so PostgreSQL costs more per bucket than a Redis hash field. Measured on PostgreSQL 17, including the primary key and retention indexes:
+
+| Row | On disk |
+| --- | --- |
+| Minute or hour counter | ~180 bytes |
+| Histogram (hour or day) | ~300 bytes |
+
+For a queue busy every minute, that is ~250 KB per metric per day of minute detail, so at the default retention (7 days of minutes, 90 of hours and days) about 6.5 MB per busy queue across both counters, both histograms and the gauge, and the same again once for the `__global__` rollup. That is several times the Redis figure below; the minute window is still the one to tune. Idle minutes are never written, on either store.
+
+`getUsage()` (the storage panel) reports `keys` as row counts, and `bytes` as the tables' real on-disk size (`pg_total_relation_size`: heap, TOAST and indexes) apportioned to queues and tiers by each row's `pg_column_size`, so the parts add up to what the tables occupy. Dead rows count until autovacuum reclaims them. `minutes`, `days` and the day range mean what they mean on Redis. `purge()` reports minute and hour rows as `keysDeleted` and day rows as `fieldsDeleted`.
 
 ## Storage
 
+These are the Redis figures; see [Sizing](#sizing) for PostgreSQL.
+
 Each snapshot is written at three resolutions at once, each with its own retention, because they cost very different amounts:
 
 | Tier | Default retention | Size per busy day, per queue and metric |
@@ -121,15 +200,16 @@ Retention is enforced by Redis. Day-scoped keys expire on their own TTL; the dai
     import { MetricsHistoryAdmin } from '@worker-manager/metrics';
 
     const admin = new MetricsHistoryAdmin({ connection });        // add `prefix` if the recorder has one
+    // or, for PostgreSQL storage: new MetricsHistoryAdmin({ store })
 
     await admin.stats();                          // bytes per tier and per queue, day range
     await admin.purge();                          // delete everything
     await admin.purge({ queue: 'mailer' });       // delete one queue
     await admin.purge({ before: '2026-06-01' });  // delete anything older than a day
 
-Both are `SCAN`-driven and confined to this package's namespace, so they never block Redis and never touch BullMQ's own keys. On a cluster they scan every master, since `SCAN` carries no key for the client to route by. Purging a single queue also subtracts it from the cross-queue rollup. Call `admin.disconnect()` when done.
+On Redis both are `SCAN`-driven and confined to this package's namespace, so they never block Redis and never touch BullMQ's own keys. On a cluster they scan every master, since `SCAN` carries no key for the client to route by. Purging a single queue also subtracts it from the cross-queue rollup. Call `admin.disconnect()` when done.
 
-`RedisMetricsHistoryProvider` exposes the same two operations to the board, which turns them into a storage panel on the Metrics history page with a confirmation before anything is deleted.
+`RedisMetricsHistoryProvider` and `PostgresMetricsHistoryProvider` expose the same two operations to the board, which turns them into a storage panel on the Metrics history page with a confirmation before anything is deleted.
 
 ## Scope
 

package/dist/HistoryAdmin.d.ts

@@ -1,7 +1,12 @@
-import { type MetricsConnection } from './connection';
+import type { MetricsConnection } from './connection';
+import type { HistoryAdministration, MetricsStore } from './store';
+export { parseHistoryKey } from './RedisHistoryAdmin';
 export interface TierStats {
     keys: number;
-    /** Sum of `MEMORY USAGE` over this tier's keys, in bytes. */
+    /**
+     * Redis: sum of `MEMORY USAGE` over this tier's keys. PostgreSQL: this tier's share of the
+     * tables' on-disk size. In bytes either way.
+     */
     bytes: number;
 }
 export interface HistoryQueueStats {
@@ -36,99 +41,30 @@ export interface PurgeResult {
     /** Day fields removed from totals hashes. */
     fieldsDeleted: number;
 }
-export interface MetricsHistoryAdminOptions {
+export type MetricsHistoryAdminOptions = {
+    /** Redis. Shorthand for `store: new RedisMetricsStore({ connection, prefix })`. */
     connection: MetricsConnection;
     /** Must match the recorder's. See `MetricsRecorderOptions.prefix`. */
     prefix?: string;
-}
+    store?: never;
+} | {
+    /** Where the history lives, e.g. a `PostgresMetricsStore`. Left open on `disconnect()`. */
+    store: MetricsStore;
+    connection?: never;
+    prefix?: never;
+};
 export type HistoryTier = 'minute' | 'hour' | 'day';
-interface ParsedKey {
-    queue: string;
-    metric: string;
-    tier: HistoryTier;
-    /** ISO day the key covers, `null` for the daily totals hash. */
-    day: string | null;
-}
 /**
- * Parses the three key shapes from the right, because queue names may themselves contain
- * colons:
- *
- *   <ns>:<queue>:<metric>:<day>         minute buckets
- *   <ns>:<queue>:<metric>:hour:<day>    hourly rollup
- *   <ns>:<queue>:<metric>:totals        daily totals
- *
- * The metric segment is checked against the known set, so a queue named `hour` or one
- * ending in `:completed` still resolves correctly. Anything that doesn't fit returns null
- * and is then reported but never deleted, so a stray key can't be destroyed by accident.
+ * Inspection and cleanup for the history written by `MetricsRecorder`, in whichever store it
+ * lives. See `RedisHistoryAdmin` and `PostgresHistoryAdmin` for what each one measures.
  */
-export declare function parseHistoryKey(key: string, namespace: string): ParsedKey | null;
-/**
- * Inspection and cleanup for the Redis keys written by `MetricsRecorder`.
- *
- * Every operation is confined to the recorder's namespace and driven by SCAN, so it never
- * blocks Redis and never touches BullMQ's own keys. Deletes use UNLINK.
- */
-export declare class MetricsHistoryAdmin {
-    private readonly redis;
-    private readonly keys;
-    private readonly ownsRedis;
+export declare class MetricsHistoryAdmin implements HistoryAdministration {
+    private readonly admin;
+    /** Set only when this admin built the store itself, from a `connection`. */
+    private readonly ownedStore;
     constructor(opts: MetricsHistoryAdminOptions);
+    /** Closes the Redis connection this admin opened itself. A connection handed in is left open. */
     disconnect(): void;
-    /**
-     * Per-queue footprint of the stored history.
-     *
-     * Every key has to be measured individually, since only `MEMORY USAGE` knows what a hash
-     * really costs. Issuing those one at a time would mean a round trip per key, which at a
-     * 90-day retention across a dozen queues runs into the thousands, so the measurements go
-     * out in pipelined batches instead. Still an ops-scale call rather than a hot path: it
-     * reads the whole namespace, so it belongs behind a debug endpoint, not a poll.
-     */
     stats(): Promise<HistoryStats>;
-    /**
-     * Size and entry count for each key, in pipelined batches so the cost is a handful of
-     * round trips rather than one per key. A key that expires between the scan and the
-     * measurement simply reads as zero rather than failing the whole call.
-     */
-    private measure;
-    /**
-     * Deletes recorded history. Purging a single queue also subtracts that queue's minutes
-     * from the global rollup, so the cross-queue chart stays correct instead of keeping the
-     * removed queue's throughput folded into it forever.
-     *
-     * That correction covers the counter metrics only. The global runtime, waittime and
-     * queueage rollups keep the purged queue's contribution until their own retention drops
-     * it: a packed bucket vector cannot be decremented field by field, and a max gauge has no
-     * record of which queue produced the maximum, so there is nothing to subtract. The
-     * per-queue keys are still deleted either way. See SUMMABLE_METRICS.
-     */
     purge(opts?: PurgeOptions): Promise<PurgeResult>;
-    /**
-     * Removes one queue's buckets from the matching global key, so the cross-queue series
-     * reflects the queues that are left rather than keeping the removed queue folded in.
-     * Each tier is corrected from its own source key, because the tiers have independent
-     * retention and the minute hash may already be gone while the hourly one survives.
-     * Fields that drain to zero are dropped: the recorder never writes a zero bucket, so a
-     * leftover zero would read as recorded-but-idle instead of not recorded.
-     * Returns the number of global keys it deleted.
-     *
-     * Only the summable metrics are touched; the latency ones are skipped outright rather than
-     * silently producing a no-op subtraction of their packed values. See SUMMABLE_METRICS.
-     */
-    private subtractDayFromGlobal;
-    /**
-     * Same idea for the daily rollup: the global totals hash is the sum of the per-queue
-     * totals hashes, so it is corrected from those rather than re-derived from day hashes,
-     * which may already have expired. Returns the number of global fields it removed.
-     *
-     * Skips the latency metrics for the same reason as subtractDayFromGlobal.
-     */
-    private subtractTotalsFromGlobal;
-    /**
-     * SCAN over the namespace, once per master: SCAN carries no key, so a cluster client has
-     * no slot to route by and would answer from one arbitrary node. SCAN may also hand back the
-     * same key on more than one cursor iteration, which would double-count in `stats()`, so
-     * emissions are de-duped here. The set is bounded by queues x metrics x retention days.
-     */
-    private scan;
 }
-export {};

package/dist/HistoryAdmin.js

@@ -1,344 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MetricsHistoryAdmin = void 0;
-exports.parseHistoryKey = parseHistoryKey;
-const connection_1 = require("./connection");
-const keys_1 = require("./keys");
-const SCAN_COUNT = 500;
-const BATCH = 256;
-/** Keys per pipelined `stats()` batch. Each key costs two commands. */
-const MEASURE_BATCH = 250;
-const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
-const METRICS = ['completed', 'failed', 'runtime', 'waittime', 'queueage'];
+exports.MetricsHistoryAdmin = exports.parseHistoryKey = void 0;
+const RedisMetricsStore_1 = require("./RedisMetricsStore");
+var RedisHistoryAdmin_1 = require("./RedisHistoryAdmin");
+Object.defineProperty(exports, "parseHistoryKey", { enumerable: true, get: function () { return RedisHistoryAdmin_1.parseHistoryKey; } });
 /**
- * Metrics whose global rollup is a plain summable counter, so one queue's share can be taken
- * back out of it with HINCRBY. The latency metrics are deliberately absent: runtime and
- * waittime pack a whole bucket vector into a single field and queueage holds a max gauge,
- * and neither can be corrected by a scalar decrement. See `purge`.
- */
-const SUMMABLE_METRICS = ['completed', 'failed'];
-/**
- * Parses the three key shapes from the right, because queue names may themselves contain
- * colons:
- *
- *   <ns>:<queue>:<metric>:<day>         minute buckets
- *   <ns>:<queue>:<metric>:hour:<day>    hourly rollup
- *   <ns>:<queue>:<metric>:totals        daily totals
- *
- * The metric segment is checked against the known set, so a queue named `hour` or one
- * ending in `:completed` still resolves correctly. Anything that doesn't fit returns null
- * and is then reported but never deleted, so a stray key can't be destroyed by accident.
- */
-function parseHistoryKey(key, namespace) {
-    const prefix = `${namespace}:`;
-    if (!key.startsWith(prefix)) {
-        return null;
-    }
-    const parts = key.slice(prefix.length).split(':');
-    if (parts.length < 3) {
-        return null;
-    }
-    const last = parts[parts.length - 1];
-    if (last === 'totals' && METRICS.includes(parts[parts.length - 2])) {
-        const queue = parts.slice(0, -2).join(':');
-        return queue ? { queue, metric: parts[parts.length - 2], tier: 'day', day: null } : null;
-    }
-    if (!DAY_PATTERN.test(last)) {
-        return null;
-    }
-    if (parts.length >= 4 && parts[parts.length - 2] === keys_1.HOUR_TIER) {
-        const metric = parts[parts.length - 3];
-        const queue = parts.slice(0, -3).join(':');
-        return queue && METRICS.includes(metric) ? { queue, metric, tier: 'hour', day: last } : null;
-    }
-    const metric = parts[parts.length - 2];
-    const queue = parts.slice(0, -2).join(':');
-    return queue && METRICS.includes(metric) ? { queue, metric, tier: 'minute', day: last } : null;
-}
-function emptyTiers() {
-    return {
-        minute: { keys: 0, bytes: 0 },
-        hour: { keys: 0, bytes: 0 },
-        day: { keys: 0, bytes: 0 },
-    };
-}
-/** The global rollup key mirroring a per-queue key, same tier and same day. */
-function globalKeyFor(keys, parsed) {
-    if (parsed.day === null) {
-        return keys.totals(keys_1.GLOBAL_QUEUE, parsed.metric);
-    }
-    return parsed.tier === 'hour'
-        ? keys.hour(keys_1.GLOBAL_QUEUE, parsed.metric, parsed.day)
-        : keys.day(keys_1.GLOBAL_QUEUE, parsed.metric, parsed.day);
-}
-function toDay(value) {
-    if (typeof value === 'string') {
-        if (!DAY_PATTERN.test(value)) {
-            throw new Error(`Expected a YYYY-MM-DD day or a Date, got "${value}"`);
-        }
-        return value;
-    }
-    return value.toISOString().slice(0, 10);
-}
-/**
- * Inspection and cleanup for the Redis keys written by `MetricsRecorder`.
- *
- * Every operation is confined to the recorder's namespace and driven by SCAN, so it never
- * blocks Redis and never touches BullMQ's own keys. Deletes use UNLINK.
+ * Inspection and cleanup for the history written by `MetricsRecorder`, in whichever store it
+ * lives. See `RedisHistoryAdmin` and `PostgresHistoryAdmin` for what each one measures.
  */
 class MetricsHistoryAdmin {
     constructor(opts) {
-        const { client, owned } = (0, connection_1.resolveClient)(opts.connection);
-        this.redis = client;
-        this.ownsRedis = owned;
-        this.keys = (0, keys_1.metricsKeys)((0, keys_1.resolveNamespace)(opts.prefix, (0, connection_1.isCluster)(client)));
-    }
-    disconnect() {
-        if (this.ownsRedis) {
-            this.redis.disconnect();
-        }
-    }
-    /**
-     * Per-queue footprint of the stored history.
-     *
-     * Every key has to be measured individually, since only `MEMORY USAGE` knows what a hash
-     * really costs. Issuing those one at a time would mean a round trip per key, which at a
-     * 90-day retention across a dozen queues runs into the thousands, so the measurements go
-     * out in pipelined batches instead. Still an ops-scale call rather than a hot path: it
-     * reads the whole namespace, so it belongs behind a debug endpoint, not a poll.
-     */
-    async stats() {
-        var _a;
-        const byQueue = new Map();
-        const tiers = emptyTiers();
-        let keys = 0;
-        let bytes = 0;
-        let minutes = 0;
-        let oldestDay = null;
-        let newestDay = null;
-        const found = [];
-        for await (const key of this.scan()) {
-            const parsed = parseHistoryKey(key, this.keys.namespace);
-            if (parsed) {
-                found.push({ key, parsed });
-            }
-        }
-        const measurements = await this.measure(found.map((item) => item.key));
-        for (const [index, { parsed }] of found.entries()) {
-            const { size, len } = measurements[index];
-            const entry = (_a = byQueue.get(parsed.queue)) !== null && _a !== void 0 ? _a : {
-                queue: parsed.queue,
-                keys: 0,
-                bytes: 0,
-                minutes: 0,
-                days: [],
-                tiers: emptyTiers(),
-            };
-            entry.keys += 1;
-            entry.bytes += size;
-            entry.tiers[parsed.tier].keys += 1;
-            entry.tiers[parsed.tier].bytes += size;
-            keys += 1;
-            bytes += size;
-            tiers[parsed.tier].keys += 1;
-            tiers[parsed.tier].bytes += size;
-            if (parsed.tier === 'minute') {
-                entry.minutes += len;
-                minutes += len;
-            }
-            if (parsed.day) {
-                entry.days.push(parsed.day);
-                if (oldestDay === null || parsed.day < oldestDay) {
-                    oldestDay = parsed.day;
-                }
-                if (newestDay === null || parsed.day > newestDay) {
-                    newestDay = parsed.day;
-                }
-            }
-            byQueue.set(parsed.queue, entry);
-        }
-        const queues = [...byQueue.values()].sort((a, b) => b.bytes - a.bytes);
-        for (const queue of queues) {
-            queue.days = [...new Set(queue.days)].sort();
-        }
-        return { keys, bytes, minutes, oldestDay, newestDay, tiers, queues };
-    }
-    /**
-     * Size and entry count for each key, in pipelined batches so the cost is a handful of
-     * round trips rather than one per key. A key that expires between the scan and the
-     * measurement simply reads as zero rather than failing the whole call.
-     */
-    async measure(keys) {
-        var _a, _b, _c, _d;
-        const out = [];
-        for (let i = 0; i < keys.length; i += MEASURE_BATCH) {
-            const chunk = keys.slice(i, i + MEASURE_BATCH);
-            const pipeline = this.redis.pipeline();
-            for (const key of chunk) {
-                pipeline.memory('USAGE', key);
-                pipeline.hlen(key);
-            }
-            const res = await pipeline.exec();
-            for (let j = 0; j < chunk.length; j++) {
-                out.push({
-                    size: Number((_b = (_a = res === null || res === void 0 ? void 0 : res[j * 2]) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : 0) || 0,
-                    len: Number((_d = (_c = res === null || res === void 0 ? void 0 : res[j * 2 + 1]) === null || _c === void 0 ? void 0 : _c[1]) !== null && _d !== void 0 ? _d : 0) || 0,
-                });
-            }
-        }
-        return out;
-    }
-    /**
-     * Deletes recorded history. Purging a single queue also subtracts that queue's minutes
-     * from the global rollup, so the cross-queue chart stays correct instead of keeping the
-     * removed queue's throughput folded into it forever.
-     *
-     * That correction covers the counter metrics only. The global runtime, waittime and
-     * queueage rollups keep the purged queue's contribution until their own retention drops
-     * it: a packed bucket vector cannot be decremented field by field, and a max gauge has no
-     * record of which queue produced the maximum, so there is nothing to subtract. The
-     * per-queue keys are still deleted either way. See SUMMABLE_METRICS.
-     */
-    async purge(opts = {}) {
-        const before = opts.before === undefined ? null : toDay(opts.before);
-        const result = { keysDeleted: 0, fieldsDeleted: 0 };
-        const dayKeys = [];
-        const totalsKeys = [];
-        for await (const key of this.scan()) {
-            const parsed = parseHistoryKey(key, this.keys.namespace);
-            if (!parsed) {
-                continue;
-            }
-            if (opts.queue !== undefined && parsed.queue !== opts.queue) {
-                continue;
-            }
-            if (parsed.day === null) {
-                totalsKeys.push({ key, parsed });
-            }
-            else if (before === null || parsed.day < before) {
-                dayKeys.push({ key, parsed });
-            }
+        if (opts.store) {
+            this.admin = opts.store.administration();
+            this.ownedStore = null;
         }
-        // Rewriting the global rollup only makes sense when a single queue is being removed:
-        // a full purge drops the global keys outright, along with everything else.
-        const adjustGlobal = opts.queue !== undefined && opts.queue !== keys_1.GLOBAL_QUEUE;
-        for (const { key, parsed } of dayKeys) {
-            if (adjustGlobal) {
-                result.keysDeleted += await this.subtractDayFromGlobal(key, parsed);
-            }
-            result.keysDeleted += await this.redis.unlink(key);
+        else {
+            const store = new RedisMetricsStore_1.RedisMetricsStore({ connection: opts.connection, prefix: opts.prefix });
+            this.admin = store.administration();
+            this.ownedStore = store;
         }
-        for (const { key, parsed } of totalsKeys) {
-            const stale = (await this.redis.hkeys(key)).filter((day) => before === null || day < before);
-            if (adjustGlobal && stale.length > 0) {
-                const totals = await this.redis.hmget(key, ...stale);
-                result.fieldsDeleted += await this.subtractTotalsFromGlobal(parsed.metric, stale, totals);
-            }
-            if (before === null) {
-                result.keysDeleted += await this.redis.unlink(key);
-                continue;
-            }
-            for (let i = 0; i < stale.length; i += BATCH) {
-                result.fieldsDeleted += await this.redis.hdel(key, ...stale.slice(i, i + BATCH));
-            }
-            if ((await this.redis.hlen(key)) === 0) {
-                result.keysDeleted += await this.redis.unlink(key);
-            }
-        }
-        return result;
     }
-    /**
-     * Removes one queue's buckets from the matching global key, so the cross-queue series
-     * reflects the queues that are left rather than keeping the removed queue folded in.
-     * Each tier is corrected from its own source key, because the tiers have independent
-     * retention and the minute hash may already be gone while the hourly one survives.
-     * Fields that drain to zero are dropped: the recorder never writes a zero bucket, so a
-     * leftover zero would read as recorded-but-idle instead of not recorded.
-     * Returns the number of global keys it deleted.
-     *
-     * Only the summable metrics are touched; the latency ones are skipped outright rather than
-     * silently producing a no-op subtraction of their packed values. See SUMMABLE_METRICS.
-     */
-    async subtractDayFromGlobal(key, parsed) {
-        if (parsed.day === null || !SUMMABLE_METRICS.includes(parsed.metric)) {
-            return 0;
-        }
-        const minutes = await this.redis.hgetall(key);
-        const globalDay = globalKeyFor(this.keys, parsed);
-        const pipeline = this.redis.multi();
-        const touched = [];
-        for (const field of Object.keys(minutes)) {
-            const value = Number(minutes[field]) || 0;
-            if (value === 0) {
-                continue;
-            }
-            touched.push(field);
-            pipeline.hincrby(globalDay, field, -value);
-        }
-        if (touched.length === 0) {
-            return 0;
-        }
-        const res = await pipeline.exec();
-        const drained = touched.filter((_, i) => { var _a, _b; return Number((_b = (_a = res === null || res === void 0 ? void 0 : res[i]) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : 0) <= 0; });
-        for (let i = 0; i < drained.length; i += BATCH) {
-            await this.redis.hdel(globalDay, ...drained.slice(i, i + BATCH));
-        }
-        return (await this.redis.hlen(globalDay)) === 0 ? await this.redis.unlink(globalDay) : 0;
+    /** Closes the Redis connection this admin opened itself. A connection handed in is left open. */
+    disconnect() {
+        var _a;
+        void ((_a = this.ownedStore) === null || _a === void 0 ? void 0 : _a.close());
     }
-    /**
-     * Same idea for the daily rollup: the global totals hash is the sum of the per-queue
-     * totals hashes, so it is corrected from those rather than re-derived from day hashes,
-     * which may already have expired. Returns the number of global fields it removed.
-     *
-     * Skips the latency metrics for the same reason as subtractDayFromGlobal.
-     */
-    async subtractTotalsFromGlobal(metric, days, values) {
-        if (!SUMMABLE_METRICS.includes(metric)) {
-            return 0;
-        }
-        const globalTotals = this.keys.totals(keys_1.GLOBAL_QUEUE, metric);
-        const pipeline = this.redis.multi();
-        const touched = [];
-        days.forEach((day, i) => {
-            const value = Number(values[i]) || 0;
-            if (value === 0) {
-                return;
-            }
-            touched.push(day);
-            pipeline.hincrby(globalTotals, day, -value);
-        });
-        if (touched.length === 0) {
-            return 0;
-        }
-        const res = await pipeline.exec();
-        const drained = touched.filter((_, i) => { var _a, _b; return Number((_b = (_a = res === null || res === void 0 ? void 0 : res[i]) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : 0) <= 0; });
-        let removed = 0;
-        for (let i = 0; i < drained.length; i += BATCH) {
-            removed += await this.redis.hdel(globalTotals, ...drained.slice(i, i + BATCH));
-        }
-        return removed;
+    stats() {
+        return this.admin.stats();
     }
-    /**
-     * SCAN over the namespace, once per master: SCAN carries no key, so a cluster client has
-     * no slot to route by and would answer from one arbitrary node. SCAN may also hand back the
-     * same key on more than one cursor iteration, which would double-count in `stats()`, so
-     * emissions are de-duped here. The set is bounded by queues x metrics x retention days.
-     */
-    async *scan() {
-        const seen = new Set();
-        for (const target of (0, connection_1.scanTargets)(this.redis)) {
-            let cursor = '0';
-            do {
-                const [next, batch] = await target.scan(cursor, 'MATCH', this.keys.scanPattern, 'COUNT', SCAN_COUNT);
-                cursor = next;
-                for (const key of batch) {
-                    if (!seen.has(key)) {
-                        seen.add(key);
-                        yield key;
-                    }
-                }
-            } while (cursor !== '0');
-        }
+    purge(opts = {}) {
+        return this.admin.purge(opts);
     }
 }
 exports.MetricsHistoryAdmin = MetricsHistoryAdmin;