@adonis-agora/telescope 0.22.0 → 0.23.0

package/dist/src/stores/tiered.js

@@ -0,0 +1,254 @@
+import { mergeNewestFirst } from './parquet.js';
+import { resolvePage } from './parquet_format.js';
+/**
+ * A two-tier {@link TelescopeStore}: a hot store kept minutes deep and a Parquet cold
+ * tier for everything older.
+ *
+ * - **Writes** only reach the hot store.
+ * - **`prune(olderThan, keepLast)`** first moves hot entries older than
+ *   `now - hotFor` (and newer than `olderThan`) to cold, deleting them from hot only
+ *   after the files are written; then applies the retention cutoff to the cold tier
+ *   (whole hourly files); then compacts closed hours. A failed write deletes the files
+ *   it wrote and leaves the hot store untouched, so the next cycle retries.
+ * - **Reads** go to hot first and to cold for whatever the answer still needs, merged
+ *   newest-first without duplicate ids, so `{ page, size }` pages straight across the
+ *   tier boundary. If the cold tier cannot be read, hot results are returned and a
+ *   warning is logged; the dashboard never fails because of the cold tier.
+ */
+export class TieredTelescopeStore {
+    hot;
+    cold;
+    hotForMs;
+    moveBatchSize;
+    moveFlushSize;
+    compactEnabled;
+    logger;
+    lastWarnAt = 0;
+    report = null;
+    constructor(options) {
+        if (!(options.hotForMs > 0)) {
+            throw new Error('@adonis-agora/telescope: storage.tiered() needs a positive `hotFor`.');
+        }
+        this.hot = options.hot;
+        this.cold = options.cold;
+        this.hotForMs = options.hotForMs;
+        this.moveBatchSize = Math.max(1, Math.floor(options.moveBatchSize ?? 5_000));
+        this.moveFlushSize = Math.max(this.moveBatchSize, Math.floor(options.moveFlushSize ?? 50_000));
+        this.compactEnabled = options.compact ?? true;
+        this.logger = options.logger ?? console;
+    }
+    record(input) {
+        return this.hot.record(input);
+    }
+    async get(id) {
+        const hot = await this.hot.get(id);
+        if (hot)
+            return hot;
+        return this.coldRead('get', () => this.cold.get(id), null);
+    }
+    async list(query = {}) {
+        const { offset, size } = resolvePage(query);
+        const { page: _page, size: _size, ...filters } = query;
+        if (size === undefined) {
+            const [hot, cold] = await Promise.all([
+                this.hot.list(filters),
+                this.coldRead('list', () => this.cold.top(filters, undefined), []),
+            ]);
+            return mergeNewestFirst(hot, cold);
+        }
+        // Each tier's newest `offset + size` is enough to produce the page from their merge.
+        const need = offset + size;
+        const hot = await this.hot.list({ ...filters, page: 1, size: need });
+        if (hot.length === need) {
+            const oldestHot = hot[hot.length - 1].createdAt;
+            const newestCold = await this.coldRead('list', () => this.cold.newestCreatedAt(filters), null);
+            if (newestCold === null || newestCold < oldestHot)
+                return hot.slice(offset, need);
+        }
+        const cold = await this.coldRead('list', () => this.cold.top(filters, need), []);
+        return mergeNewestFirst(hot, cold).slice(offset, need);
+    }
+    async count() {
+        const [hot, cold] = await Promise.all([
+            this.hot.count(),
+            this.coldRead('count', () => this.cold.count(), 0),
+        ]);
+        return hot + cold;
+    }
+    /**
+     * The union's top traces: each tier's top `offset + size` by last-seen, merged by the
+     * newer of the two timestamps. A trace in the union's top N is necessarily in the top
+     * N of the tier where it was last seen, so nothing is missed.
+     */
+    async listTraceIds(query) {
+        const size = Math.max(0, Math.floor(query.size));
+        const offset = (Math.max(1, Math.floor(query.page ?? 1)) - 1) * size;
+        const need = offset + size;
+        if (need === 0)
+            return [];
+        const window = {
+            ...(query.before !== undefined ? { before: query.before } : {}),
+            ...(query.after !== undefined ? { after: query.after } : {}),
+        };
+        const [hot, cold] = await Promise.all([
+            this.hot.listTraceIds
+                ? this.hot.listTraceIds({ ...window, size: need, page: 1 })
+                : traceIdsFromList(await this.hot.list(window), need),
+            this.coldRead('listTraceIds', () => this.cold.topTraceIds(window, need), []),
+        ]);
+        const lastAt = new Map();
+        for (const row of [...hot, ...cold]) {
+            const at = row.lastAt.getTime();
+            const seen = lastAt.get(row.traceId);
+            if (seen === undefined || at > seen)
+                lastAt.set(row.traceId, at);
+        }
+        return [...lastAt.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(offset, need)
+            .map(([traceId, at]) => ({ traceId, lastAt: new Date(at) }));
+    }
+    async countByBucket(query) {
+        const [hot, cold] = await Promise.all([
+            this.hot.countByBucket ? this.hot.countByBucket(query) : this.bucketsFromHotList(query),
+            this.coldRead('countByBucket', () => this.cold.countByBucket(query), []),
+        ]);
+        const tally = new Map();
+        for (const row of [...hot, ...cold]) {
+            const key = `${row.index}\u0000${row.type}`;
+            const seen = tally.get(key);
+            if (seen === undefined)
+                tally.set(key, { ...row });
+            else
+                seen.count += row.count;
+        }
+        return [...tally.values()];
+    }
+    async prune(olderThan, keepLast) {
+        const hotCutoff = new Date(Date.now() - this.hotForMs);
+        const report = {
+            moved: 0,
+            hotDeleted: 0,
+            coldExpired: 0,
+            compactedFiles: 0,
+        };
+        this.report = report;
+        if (hotCutoff > olderThan) {
+            // Move-then-delete. A failure in `moveToCold` leaves the hot store as it was.
+            // With `keepLast`, hot entries already past retention move too, so the cold
+            // tier's expiry applies the count across both tiers.
+            const moveAfter = keepLast === undefined ? olderThan : new Date(0);
+            report.moved = await this.moveToCold(moveAfter, hotCutoff);
+            report.hotDeleted = await this.hot.prune(hotCutoff);
+        }
+        else {
+            // Retention is shorter than the hot window: nothing ever reaches cold.
+            report.hotDeleted = await this.hot.prune(olderThan, keepLast);
+        }
+        try {
+            report.coldExpired = await this.cold.expire(olderThan, keepLast);
+            if (this.compactEnabled)
+                report.compactedFiles = await this.cold.compact(hotCutoff);
+        }
+        catch (error) {
+            report.error = message(error);
+            this.logger.warn(`Telescope cold tier maintenance failed: ${report.error}`);
+        }
+        return Math.max(0, report.hotDeleted - report.moved) + report.coldExpired;
+    }
+    /** What the last prune cycle moved, deleted and compacted (null before the first). */
+    lastPrune() {
+        return this.report ? { ...this.report } : null;
+    }
+    async clear() {
+        await Promise.all([this.hot.clear(), this.cold.clear()]);
+    }
+    /** Release the cold engine (DuckDB holds a native instance). */
+    async close() {
+        await this.cold.close();
+    }
+    /**
+     * Copy hot entries in `[after, before)` to cold. Pages are offset-based over a fixed
+     * window that nothing is deleted from until the whole move succeeded, so no entry is
+     * skipped; entries reach the window only by ageing past `before`, after this cycle's
+     * snapshot. Resolves to the number of entries written.
+     */
+    async moveToCold(after, before) {
+        const window = { after: new Date(after.getTime() - 1), before };
+        const written = [];
+        let buffered = [];
+        let moved = 0;
+        try {
+            for (let page = 1;; page++) {
+                const rows = await this.hot.list({ ...window, page, size: this.moveBatchSize });
+                buffered.push(...rows);
+                if (buffered.length >= this.moveFlushSize ||
+                    (rows.length < this.moveBatchSize && buffered.length > 0)) {
+                    written.push(...(await this.cold.write(buffered)));
+                    moved += buffered.length;
+                    buffered = [];
+                }
+                if (rows.length < this.moveBatchSize)
+                    break;
+            }
+        }
+        catch (error) {
+            await this.cold.location.delete(written).catch(() => undefined);
+            throw error;
+        }
+        return moved;
+    }
+    async bucketsFromHotList(query) {
+        const startMs = query.after.getTime();
+        const bucketMs = Math.max(1, Math.floor(query.bucketMs));
+        const rows = await this.hot.list({
+            after: query.after,
+            before: new Date(query.before.getTime() + 1),
+            ...(query.type !== undefined ? { type: query.type } : {}),
+        });
+        const tally = new Map();
+        for (const entry of rows) {
+            const index = Math.floor((entry.createdAt.getTime() - startMs) / bucketMs);
+            const key = `${index}\u0000${entry.type}`;
+            const seen = tally.get(key);
+            if (seen === undefined)
+                tally.set(key, { index, type: entry.type, count: 1 });
+            else
+                seen.count += 1;
+        }
+        return [...tally.values()];
+    }
+    /** Run a cold read; on failure log (at most once a minute) and use `fallback`. */
+    async coldRead(what, read, fallback) {
+        try {
+            return await read();
+        }
+        catch (error) {
+            const now = Date.now();
+            if (now - this.lastWarnAt > 60_000) {
+                this.lastWarnAt = now;
+                this.logger.warn(`Telescope cold tier unavailable (${what}); serving hot entries only: ${message(error)}`);
+            }
+            return fallback;
+        }
+    }
+}
+function traceIdsFromList(entries, limit) {
+    const lastAt = new Map();
+    for (const entry of entries) {
+        if (entry.traceId === null)
+            continue;
+        const at = entry.createdAt.getTime();
+        const seen = lastAt.get(entry.traceId);
+        if (seen === undefined || at > seen)
+            lastAt.set(entry.traceId, at);
+    }
+    return [...lastAt.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, limit)
+        .map(([traceId, at]) => ({ traceId, lastAt: new Date(at) }));
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=tiered.js.map

package/dist/src/stores/tiered.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tiered.js","sourceRoot":"","sources":["../../../src/stores/tiered.ts"],"names":[],"mappings":"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"}

package/dist/src/ui/index.d.ts

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.22.0";
+export declare const VERSION = "0.23.0";
 export type { AccessDeniedInfo, AccessDeniedPageOptions, AccessDeniedReason, } from './access_denied_page.js';
 export { CONSOLE as ACCESS_DENIED_CONSOLE, escapeHtml, renderAccessDeniedPage, resolveAccessDeniedPage, } from './access_denied_page.js';
 export type { EntrySummary, RetentionInfo, RetentionOptions, RetentionPruneOptions, RetentionSamplingRate, } from './api.js';

package/dist/src/ui/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.22.0';
+export const VERSION = '0.23.0';
 // — the built-in "access denied" page (what a browser sees on a refused page navigation) —
 export { CONSOLE as ACCESS_DENIED_CONSOLE, escapeHtml, renderAccessDeniedPage, resolveAccessDeniedPage, } from './access_denied_page.js';
 // — JSON API —

package/dist/src/watchers/index.d.ts

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export declare const VERSION = "0.22.0";
+export declare const VERSION = "0.23.0";
 export type { CacheEntryContent, CacheEventLike, CacheOperation } from './cache_watcher.js';
 export { buildCacheEntry, CACHE_EVENTS, CacheWatcher } from './cache_watcher.js';
 export { nextCronRunMs } from './cron_next_run.js';

package/dist/src/watchers/index.js

@@ -1,5 +1,5 @@
 /** Keep in sync with this package's `version` in package.json. */
-export const VERSION = '0.22.0';
+export const VERSION = '0.23.0';
 // — cache watcher —
 export { buildCacheEntry, CACHE_EVENTS, CacheWatcher } from './cache_watcher.js';
 export { nextCronRunMs } from './cron_next_run.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/telescope",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Laravel Telescope-style headless observability for AdonisJS — records HTTP requests and every Agora diagnostics event as queryable entries, plus opt-in subpaths for per-technology watchers, a web dashboard, AI exception diagnosis, and alerting.",
   "license": "MIT",
   "repository": {
@@ -133,13 +133,18 @@
     "@adonisjs/lucid": "^22.4.0",
     "@adonisjs/mail": "^10.2.0",
     "@anthropic-ai/sdk": ">=0.32.0 <1.0.0",
+    "@aws-sdk/client-s3": "^3.400.0",
+    "@duckdb/node-api": ">=1.5.6-r.1 <2.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/exporter-logs-otlp-http": ">=0.200.0 <1.0.0",
     "@opentelemetry/exporter-trace-otlp-http": ">=0.200.0 <1.0.0",
     "@opentelemetry/resources": "^2.0.0",
     "@opentelemetry/sdk-logs": ">=0.200.0 <1.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
-    "cron-parser": "^4.0.0 || ^5.0.0"
+    "cron-parser": "^4.0.0 || ^5.0.0",
+    "hyparquet": "^1.31.0",
+    "hyparquet-compressors": "^1.1.0",
+    "hyparquet-writer": ">=0.17.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@adonisjs/lucid": {
@@ -174,13 +179,30 @@
     },
     "cron-parser": {
       "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@duckdb/node-api": {
+      "optional": true
+    },
+    "hyparquet": {
+      "optional": true
+    },
+    "hyparquet-compressors": {
+      "optional": true
+    },
+    "hyparquet-writer": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@adonisjs/assembler": "8.5.2",
     "@adonisjs/core": "7.6.0",
     "@adonisjs/lucid": "22.4.2",
-    "@anthropic-ai/sdk": "0.133.0",
+    "@anthropic-ai/sdk": "0.135.0",
+    "@aws-sdk/client-s3": "3.1154.0",
+    "@duckdb/node-api": "1.5.6-r.1",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/exporter-logs-otlp-http": "0.223.0",
     "@opentelemetry/exporter-trace-otlp-http": "0.223.0",
@@ -192,9 +214,12 @@
     "@types/node": "26.6.5",
     "better-sqlite3": "13.0.3",
     "cron-parser": "5.10.2",
+    "hyparquet": "1.31.5",
+    "hyparquet-compressors": "1.1.2",
+    "hyparquet-writer": "0.17.0",
     "luxon": "3.7.2",
     "typescript": "7.0.2",
-    "vitest": "5.0.4"
+    "vitest": "5.0.5"
   },
   "engines": {
     "node": ">=24"

package/skills/telescope-setup/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up @adonis-agora/telescope in an AdonisJS app. Covers node ace configure
   codemods (telescope_provider + TelescopeMiddleware on the server stack +
   config/telescope.ts), defineConfig keys (enabled/store/stores/watchers/redact),
-  the storage.memory and storage.lucid drivers, the headless TelescopeService query
+  the storage.memory, storage.lucid and storage.tiered drivers, the headless TelescopeService query
   API (list/find/byTrace/count/topFamilies/topTags/getHealth), recordException for
   non-HTTP paths, opt-in requestCapture body gates, and why /telescope 404s without
   @adonis-agora/telescope-ui. Use for "install telescope", "telemetry is empty",

package/skills/telescope-storage-retention/SKILL.md

@@ -2,7 +2,8 @@
 name: telescope-storage-retention
 description: >-
   Storage, retention, redaction and sampling in @adonis-agora/telescope — the
-  storage.memory ring buffer vs the storage.lucid SQL driver (optional peer,
+  storage.memory ring buffer vs the storage.lucid SQL driver vs the
+  storage.tiered hot-plus-Parquet driver (optional peers,
   create_telescope_entries_table migration), the TelescopeStore contract
   (record/get/list/count/prune/clear), prune {after,keepLast,intervalMs}, the
   overload guard + setTelescopePaused, redact {keys,perType}, tail-sampling rules
@@ -27,9 +28,11 @@ sources:
 
 A store sits between capture and query: watchers `record` into it, and
 `TelescopeService` reads out of it. Storage is **config-driven** — build named
-drivers with the `storage` factory, pick one with `store`. Two ship in the box:
-`memory` (bounded ring buffer) and `lucid` (persistent SQL via an optional
-`@adonisjs/lucid` peer imported lazily only when selected).
+drivers with the `storage` factory, pick one with `store`. Three ship in the box:
+`memory` (bounded ring buffer), `lucid` (persistent SQL via an optional
+`@adonisjs/lucid` peer imported lazily only when selected) and `tiered` (a hot
+driver kept minutes deep plus a Parquet cold tier for everything older — see the
+Scaling storage docs).
 
 ## Setup