@adonis-agora/telescope 0.12.0 → 0.14.0

package/dist/src/watchers/redis_watcher.js

@@ -24,6 +24,19 @@ function isThenable(value) {
         'then' in value &&
         typeof value.then === 'function');
 }
+/** Default flood threshold (entries/minute) — see {@link RedisWatcherOptions.floodWarnPerMinute}. */
+const DEFAULT_FLOOD_WARN_PER_MINUTE = 600;
+/** The first argument of a redis command, as a string, or `null` when unkeyed. */
+function firstKey(command) {
+    const args = command.args;
+    if (!Array.isArray(args) || args.length === 0)
+        return null;
+    const key = args[0];
+    if (typeof key === 'string')
+        return key;
+    // ioredis passes Buffers for binary-safe keys; only decode when it is cheap.
+    return typeof Buffer !== 'undefined' && Buffer.isBuffer(key) ? key.toString('utf8') : null;
+}
 /**
  * Records every Redis command issued through `@adonisjs/redis` as a `redis`
  * telescope entry — the command name, args, connection and round-trip duration,
@@ -55,10 +68,53 @@ export class RedisWatcher {
     /** Clients we patched, with their connection name, for clean restore on stop. */
     wrapped = [];
     unsubscribeManager = null;
+    ignoreCommands;
+    ignoreKeys;
+    ignoreConnections;
+    sampleRate;
+    floodWarnPerMinute;
+    /** Flood accounting: entries recorded in the current minute, plus the loudest
+     *  command/key seen, so the warning can name the actual culprit. */
+    windowStartedAt = now();
+    windowCount = 0;
+    windowCommands = new Map();
+    windowKeyPrefixes = new Map();
+    floodWarned = false;
     /** Construct with the resolved `@adonisjs/redis` manager (or `null` when the
      *  optional peer is absent — the watcher then no-ops). */
-    constructor(manager) {
+    constructor(manager, options = {}) {
         this.manager = isManager(manager) ? manager : null;
+        this.ignoreCommands = new Set((options.ignoreCommands ?? []).map((c) => c.toUpperCase()));
+        this.ignoreKeys = options.ignoreKeys ?? [];
+        this.ignoreConnections = new Set((options.ignoreConnections ?? []).map((c) => c.toLowerCase()));
+        // Clamp rather than throw: a bad sampleRate should not take the app down at boot.
+        this.sampleRate = Math.min(1, Math.max(0, options.sampleRate ?? 1));
+        this.floodWarnPerMinute = Math.max(0, options.floodWarnPerMinute ?? DEFAULT_FLOOD_WARN_PER_MINUTE);
+    }
+    /**
+     * Whether this command is recorded. Ordered cheapest-first: the connection and
+     * command checks are set lookups, the key check walks the (usually empty) pattern
+     * list, and sampling comes last so a filtered-out command never burns entropy.
+     */
+    shouldRecord(command, connection) {
+        if (connection !== null && this.ignoreConnections.has(connection.toLowerCase()))
+            return false;
+        const name = typeof command.name === 'string' ? command.name.toUpperCase() : '';
+        if (this.ignoreCommands.has(name))
+            return false;
+        if (this.ignoreKeys.length > 0) {
+            const key = firstKey(command);
+            if (key !== null) {
+                for (const pattern of this.ignoreKeys) {
+                    const hit = typeof pattern === 'string' ? key.startsWith(pattern) : pattern.test(key);
+                    if (hit)
+                        return false;
+                }
+            }
+        }
+        if (this.sampleRate < 1 && Math.random() >= this.sampleRate)
+            return false;
+        return true;
     }
     /** Instrument current + future connections. Idempotent. A no-op when the peer
      *  is absent. */
@@ -114,6 +170,11 @@ export class RedisWatcher {
         client.__telescopeOriginalSendCommand__ = original;
         this.wrapped.push({ client, connection });
         client.sendCommand = function patchedSendCommand(command, ...rest) {
+            // Decided BEFORE the call so a filtered command costs one set lookup and
+            // never allocates a finalize closure or attaches to the command's promise.
+            if (!watcher.shouldRecord(command, connection)) {
+                return original.call(client, command, ...rest);
+            }
             const startedAt = now();
             const result = original.call(client, command, ...rest);
             if (isThenable(result)) {
@@ -129,8 +190,70 @@ export class RedisWatcher {
         };
     }
     record(command, connection, durationMs) {
+        this.accountForFlood(command);
         safeRecord(buildRedisEntry(command, connection, durationMs), 'RedisWatcher');
     }
+    /**
+     * Count what we record in a rolling one-minute window and, the first time it
+     * crosses the threshold, warn ONCE naming the loudest command and key prefix.
+     *
+     * This exists because the failure mode is silent: nothing breaks, the app is fine,
+     * and you only discover the watcher is writing 300k rows/day when a console screen
+     * gets slow enough to complain about. Naming the culprit turns the fix into a paste
+     * instead of an investigation.
+     */
+    accountForFlood(command) {
+        if (this.floodWarnPerMinute === 0 || this.floodWarned)
+            return;
+        const elapsed = now() - this.windowStartedAt;
+        if (elapsed >= 60_000) {
+            this.windowStartedAt = now();
+            this.windowCount = 0;
+            this.windowCommands.clear();
+            this.windowKeyPrefixes.clear();
+        }
+        this.windowCount++;
+        const name = typeof command.name === 'string' ? command.name.toUpperCase() : '(unknown)';
+        this.windowCommands.set(name, (this.windowCommands.get(name) ?? 0) + 1);
+        const key = firstKey(command);
+        if (key !== null) {
+            // Group by the first two colon-segments — `app:rlflx:foo` → `app:rlflx`, which
+            // is the granularity someone would actually paste into `ignoreKeys`.
+            const prefix = key.split(':').slice(0, 2).join(':');
+            this.windowKeyPrefixes.set(prefix, (this.windowKeyPrefixes.get(prefix) ?? 0) + 1);
+        }
+        if (this.windowCount < this.floodWarnPerMinute)
+            return;
+        this.floodWarned = true;
+        console.warn(formatFloodWarning(this.windowCount, this.windowCommands, this.windowKeyPrefixes));
+    }
+}
+/** Largest-count entry of a tally, or `null` when empty. */
+function topOf(tally) {
+    let top = null;
+    for (const [name, count] of tally) {
+        if (top === null || count > top.count)
+            top = { name, count };
+    }
+    return top;
+}
+/** The flood warning text. Exported for tests — the VALUE here is that the message
+ *  names the culprit and the exact option, so it is worth pinning. */
+export function formatFloodWarning(count, commands, keyPrefixes) {
+    const command = topOf(commands);
+    const prefix = topOf(keyPrefixes);
+    const lines = [
+        `Telescope: the redis watcher recorded ${count} entries in the last minute. ` +
+            'At that rate it will dominate your telescope table and slow the console down.',
+    ];
+    if (command)
+        lines.push(`  loudest command: ${command.name} (${command.count})`);
+    if (prefix) {
+        lines.push(`  loudest key prefix: ${prefix.name} (${prefix.count})`);
+        lines.push(`  to drop it: redis: { ignoreKeys: ['${prefix.name}:'] } in config/telescope_watchers.ts`);
+    }
+    lines.push('  (or set redis.floodWarnPerMinute: 0 to silence this warning)');
+    return lines.join('\n');
 }
 /** Narrow an arbitrary value to a {@link RedisManagerLike}. */
 function isManager(value) {

package/dist/src/watchers/redis_watcher.js.map

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

package/dist/stubs/config/telescope.stub

@@ -88,6 +88,26 @@ export default defineConfig({
   //   skipBody: (request) => request.url.startsWith('/webhooks/'),
   // },
 
+  /**
+   * Enrich every request entry with what only your app knows. Return 'tags' for
+   * anything you want to FILTER by in the dashboard, 'context' for detail you only
+   * want to read, and 'user' when neither ctx.auth.user nor the
+   * @adonis-agora/context userRef() applies.
+   *
+   * The classic use: have the front end send its current screen in a header, and
+   * tag the entry with it — then the dashboard answers "which requests came from
+   * the writing screen?" with its normal tag filter.
+   *
+   * SYNCHRONOUS: it runs on the recording path of every request, so read what is
+   * already on the ctx (headers, route, resolved guard state) rather than doing
+   * I/O. A throw is swallowed — enrichment never costs you the entry.
+   */
+  // requestEnrichment: (ctx) => {
+  //   // header() is optional on the framework-agnostic ctx type — hence the ?. call
+  //   const screen = ctx.request.header?.('x-screen')
+  //   return typeof screen === 'string' ? { tags: ['screen:' + screen] } : undefined
+  // },
+
   /**
    * Sensitive-data redaction. Every entry's content is scrubbed before it is
    * persisted — a built-in set of sensitive keys ('authorization', 'cookie',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/telescope",
-  "version": "0.12.0",
+  "version": "0.14.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": {