@adonis-agora/telescope 0.2.0 → 0.3.0

package/dist/src/watchers/queue_watcher.js

@@ -0,0 +1,114 @@
+import diagnostics_channel from 'node:diagnostics_channel';
+import { currentTraceId } from '../context_accessor.js';
+import { EntryType } from '../entry.js';
+import { safeRecord } from './record.js';
+/**
+ * The `node:diagnostics_channel` tracing channel `@boringnode/queue` (the engine
+ * behind the OPTIONAL peer `@adonisjs/queue`) publishes a job EXECUTION trace on.
+ * A tracing channel fires the sub-channels `<name>:start`, `:end`, `:asyncStart`,
+ * `:asyncEnd`, and `:error` around the traced async operation; we read the outcome
+ * off `:asyncEnd` (status/duration/error are mutated onto the same message during
+ * the trace's async lifecycle).
+ *
+ * `@adonisjs/queue` is not installed in this repo, so this channel name + payload
+ * shape are sourced from the engine's `src/tracing_channels.ts` rather than
+ * verified against installed types (the engine is pre-1.0, so this surface can
+ * drift). The watcher degrades to a pure no-op when nobody publishes on the
+ * channel — i.e. when the peer is absent.
+ */
+export const QUEUE_EXECUTE_CHANNEL = 'boringqueue.job.execute';
+/** Sub-channel the tracing channel fires once a traced execution settles. */
+const ASYNC_END_CHANNEL = `${QUEUE_EXECUTE_CHANNEL}:asyncEnd`;
+/** Default slow-job threshold in milliseconds. */
+const DEFAULT_SLOW_MS = 1000;
+/** Narrow an unknown tracing message to the structural shape we read. */
+function toMessage(msg) {
+    return typeof msg === 'object' && msg !== null ? msg : {};
+}
+/**
+ * Records every `@adonisjs/queue` job EXECUTION as a `job` telescope entry —
+ * capturing the queue, job name, payload, outcome (completed/failed/retrying),
+ * attempts and duration, correlated to the active trace.
+ *
+ * ## How it works
+ * `@adonisjs/queue`'s engine (`@boringnode/queue`) publishes a
+ * `node:diagnostics_channel` TRACING channel per execution attempt
+ * ({@link QUEUE_EXECUTE_CHANNEL}). The watcher subscribes to its `:asyncEnd`
+ * sub-channel — fired once the execution settles, with `status`/`duration`/`error`
+ * populated — and records one entry per attempt. Subscribing is what flips the
+ * channel's `hasSubscribers` on; with no publisher (peer absent) it is a no-op.
+ *
+ * Like the other watchers, recording is fire-and-forget and fully guarded: a
+ * telescope failure can never break or block a job.
+ */
+export class QueueWatcher {
+    type = EntryType.Job;
+    slowMs;
+    handler = null;
+    constructor(options = {}) {
+        this.slowMs = options.slowMs ?? DEFAULT_SLOW_MS;
+    }
+    /** Subscribe to the queue execution trace. Idempotent. */
+    start() {
+        if (this.handler)
+            return;
+        const handler = (msg) => this.handle(msg);
+        this.handler = handler;
+        diagnostics_channel.channel(ASYNC_END_CHANNEL).subscribe(handler);
+    }
+    /** Unsubscribe from the queue execution trace. Safe to call when never started. */
+    stop() {
+        if (!this.handler)
+            return;
+        diagnostics_channel.channel(ASYNC_END_CHANNEL).unsubscribe(this.handler);
+        this.handler = null;
+    }
+    handle(msg) {
+        safeRecord(buildJobEntry(toMessage(msg), this.slowMs), 'QueueWatcher');
+    }
+}
+/** Map a queue execution message to a telescope {@link RecordInput}. Exported so
+ *  the entry shape can be unit-tested without a real diagnostics publish. */
+export function buildJobEntry(message, slowMs = DEFAULT_SLOW_MS) {
+    const job = message.job ?? {};
+    const id = typeof job.id === 'string' ? job.id : null;
+    const name = typeof job.name === 'string' ? job.name : null;
+    const queue = typeof message.queue === 'string' ? message.queue : null;
+    const status = message.status ?? 'completed';
+    const attempts = typeof job.attempts === 'number' ? job.attempts : null;
+    const durationMs = typeof message.duration === 'number' ? Math.max(0, message.duration) : null;
+    const failed = status === 'failed' || status === 'retrying';
+    const failureReason = failed && message.error !== undefined ? errorMessage(message.error) : null;
+    const traceId = currentTraceId();
+    const content = {
+        id,
+        name,
+        queue,
+        payload: job.payload ?? null,
+        status,
+        attempts,
+        failureReason,
+        traceId,
+    };
+    const tags = ['queue', `status:${status}`];
+    if (queue)
+        tags.push(`queue:${queue}`);
+    if (name)
+        tags.push(`job:${name}`);
+    if (failed)
+        tags.push('failed');
+    if (durationMs !== null && durationMs >= slowMs)
+        tags.push('slow');
+    return {
+        type: EntryType.Job,
+        familyHash: [queue, name].filter(Boolean).join(':') || null,
+        content,
+        durationMs,
+        traceId,
+        tags,
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=queue_watcher.js.map

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

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

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

@@ -0,0 +1,103 @@
+import { type RecordInput } from '../entry.js';
+/**
+ * A single ioredis command, structurally. `name` is the command (e.g. `get`),
+ * `args` are its arguments. This is the shape of the ioredis `Command` object the
+ * client funnels every command through (`Command.name` / `Command.args`).
+ */
+export interface RedisCommandLike {
+    name?: string;
+    args?: unknown[];
+}
+/**
+ * The structural ioredis client surface this watcher wraps. `@adonisjs/redis`
+ * exposes the raw ioredis client on `connection().ioConnection`; ioredis funnels
+ * EVERY command through `sendCommand(command)`, so wrapping that single method
+ * captures everything (including pipelined / multi commands). `Command.promise`
+ * resolves with the reply, letting us time the round-trip.
+ */
+export interface RedisClientLike {
+    sendCommand(command: RedisCommandLike, ...rest: unknown[]): unknown;
+}
+/**
+ * The structural slice of a `@adonisjs/redis` connection: the raw ioredis client
+ * under `ioConnection`, and (when subscribing has occurred) the separate
+ * subscriber client. A connection name is read for tagging when present.
+ */
+export interface RedisConnectionLike {
+    connectionName?: string;
+    ioConnection?: unknown;
+    ioSubscriberConnection?: unknown;
+}
+/**
+ * The structural slice of the `@adonisjs/redis` manager: it exposes the active
+ * connections and emits a `'connection'` event (via `emittery`, returning an
+ * unsubscribe function) as each new connection is created. The watcher uses both
+ * to instrument current AND future connections.
+ */
+export interface RedisManagerLike {
+    activeConnections?: Record<string, RedisConnectionLike> | undefined;
+    on?(event: 'connection', listener: (connection: RedisConnectionLike) => void): () => void;
+}
+/** The recorded body of a `redis` entry. */
+export interface RedisEntryContent {
+    /** The command name, upper-cased (e.g. `'GET'`). */
+    command: string;
+    /** The command arguments, in order (redaction applies downstream). */
+    args: unknown[];
+    /** The connection name (e.g. `'main'`), or `null`. */
+    connection: string | null;
+    /** Round-trip duration in ms, or `null` when not awaitable. */
+    durationMs: number | null;
+    /** The active trace id at command time, or `null`. */
+    traceId: string | null;
+}
+/**
+ * Records every Redis command issued through `@adonisjs/redis` as a `redis`
+ * telescope entry — the command name, args, connection and round-trip duration,
+ * correlated to the active trace.
+ *
+ * ## How it works
+ * `@adonisjs/redis` is an OPTIONAL peer (not installed in this repo, so its surface
+ * is sourced from its types, not verified here). Its connection wrapper exposes the
+ * raw ioredis client on `connection().ioConnection`, and ioredis funnels every
+ * command through `sendCommand(command)`. The watcher monkey-patches that single
+ * method on each connection's ioredis client: it captures `{ name, args }`, times
+ * the round-trip via the command's returned promise, and records the entry. The
+ * original is always called and its result returned/thrown unchanged — recording
+ * failures are swallowed so a telescope error can never alter a command's outcome.
+ *
+ * The watcher is constructed with the `@adonisjs/redis` manager: at {@link start}
+ * it instruments every already-active connection and arms the manager's
+ * `'connection'` event so connections created later are instrumented too. Patching
+ * is per-client and idempotent; {@link stop} restores every original `sendCommand`.
+ *
+ * ## Caveat
+ * It records exactly what each wrapped client does. If telescope's own redis
+ * storage shares a connection, those commands would be captured too — use a
+ * dedicated connection for telescope storage to avoid that noise.
+ */
+export declare class RedisWatcher {
+    readonly type: "redis";
+    private readonly manager;
+    /** Clients we patched, with their connection name, for clean restore on stop. */
+    private readonly wrapped;
+    private unsubscribeManager;
+    /** Construct with the resolved `@adonisjs/redis` manager (or `null` when the
+     *  optional peer is absent — the watcher then no-ops). */
+    constructor(manager: unknown);
+    /** Instrument current + future connections. Idempotent. A no-op when the peer
+     *  is absent. */
+    start(): void;
+    /** Restore every wrapped `sendCommand` and stop watching for new connections. */
+    stop(): void;
+    /** Wrap the ioredis client(s) backing a connection. */
+    private instrument;
+    /** Monkey-patch one ioredis client's `sendCommand`. No-op when it lacks the
+     *  method or is already wrapped. */
+    private wrap;
+    private record;
+}
+/** Map a captured Redis command to a telescope {@link RecordInput}. Exported so
+ *  the entry shape can be unit-tested without a real ioredis client. */
+export declare function buildRedisEntry(command: RedisCommandLike, connection: string | null, durationMs: number | null): RecordInput<RedisEntryContent>;
+//# sourceMappingURL=redis_watcher.d.ts.map

package/dist/src/watchers/redis_watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis_watcher.d.ts","sourceRoot":"","sources":["../../../src/watchers/redis_watcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;CACrE;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,GAAG,SAAS,CAAC;IACpE,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,UAAU,EAAE,mBAAmB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC3F;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,sDAAsD;IACtD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+DAA+D;IAC/D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,sDAAsD;IACtD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAoCD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,IAAI,UAAmB;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwE;IAChG,OAAO,CAAC,kBAAkB,CAA6B;IAEvD;8DAC0D;gBAC9C,OAAO,EAAE,OAAO;IAI5B;qBACiB;IACjB,KAAK,IAAI,IAAI;IAgBb,iFAAiF;IACjF,IAAI,IAAI,IAAI;IAcZ,uDAAuD;IACvD,OAAO,CAAC,UAAU;IAOlB;wCACoC;IACpC,OAAO,CAAC,IAAI;IAgCZ,OAAO,CAAC,MAAM;CAOf;AAOD;wEACwE;AACxE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,GACxB,WAAW,CAAC,iBAAiB,CAAC,CAoBhC"}

package/dist/src/watchers/redis_watcher.js

@@ -0,0 +1,161 @@
+import { currentTraceId } from '../context_accessor.js';
+import { EntryType } from '../entry.js';
+import { safeRecord } from './record.js';
+/** Marks a client whose `sendCommand` we've already wrapped, so the same instance
+ *  (or two watchers / package copies sharing it) is never double-wrapped. A
+ *  `Symbol.for` so both copies resolve the same brand. */
+const PATCHED = Symbol.for('@agora/telescope:redisPatched');
+/** Narrow an arbitrary value to one with a usable `sendCommand`. */
+function hasSendCommand(value) {
+    if (typeof value !== 'object' || value === null || !('sendCommand' in value))
+        return false;
+    return typeof value.sendCommand === 'function';
+}
+/** Best-effort high-resolution clock; falls back to `Date.now()`. */
+function now() {
+    return typeof performance === 'object' && typeof performance.now === 'function'
+        ? performance.now()
+        : Date.now();
+}
+/** True when a value looks like a thenable (so the round-trip can be timed). */
+function isThenable(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'then' in value &&
+        typeof value.then === 'function');
+}
+/**
+ * Records every Redis command issued through `@adonisjs/redis` as a `redis`
+ * telescope entry — the command name, args, connection and round-trip duration,
+ * correlated to the active trace.
+ *
+ * ## How it works
+ * `@adonisjs/redis` is an OPTIONAL peer (not installed in this repo, so its surface
+ * is sourced from its types, not verified here). Its connection wrapper exposes the
+ * raw ioredis client on `connection().ioConnection`, and ioredis funnels every
+ * command through `sendCommand(command)`. The watcher monkey-patches that single
+ * method on each connection's ioredis client: it captures `{ name, args }`, times
+ * the round-trip via the command's returned promise, and records the entry. The
+ * original is always called and its result returned/thrown unchanged — recording
+ * failures are swallowed so a telescope error can never alter a command's outcome.
+ *
+ * The watcher is constructed with the `@adonisjs/redis` manager: at {@link start}
+ * it instruments every already-active connection and arms the manager's
+ * `'connection'` event so connections created later are instrumented too. Patching
+ * is per-client and idempotent; {@link stop} restores every original `sendCommand`.
+ *
+ * ## Caveat
+ * It records exactly what each wrapped client does. If telescope's own redis
+ * storage shares a connection, those commands would be captured too — use a
+ * dedicated connection for telescope storage to avoid that noise.
+ */
+export class RedisWatcher {
+    type = EntryType.Redis;
+    manager;
+    /** Clients we patched, with their connection name, for clean restore on stop. */
+    wrapped = [];
+    unsubscribeManager = null;
+    /** Construct with the resolved `@adonisjs/redis` manager (or `null` when the
+     *  optional peer is absent — the watcher then no-ops). */
+    constructor(manager) {
+        this.manager = isManager(manager) ? manager : null;
+    }
+    /** Instrument current + future connections. Idempotent. A no-op when the peer
+     *  is absent. */
+    start() {
+        if (!this.manager)
+            return;
+        if (this.unsubscribeManager)
+            return;
+        const active = this.manager.activeConnections;
+        if (active && typeof active === 'object') {
+            for (const connection of Object.values(active))
+                this.instrument(connection);
+        }
+        if (typeof this.manager.on === 'function') {
+            this.unsubscribeManager = this.manager.on('connection', (connection) => this.instrument(connection));
+        }
+    }
+    /** Restore every wrapped `sendCommand` and stop watching for new connections. */
+    stop() {
+        this.unsubscribeManager?.();
+        this.unsubscribeManager = null;
+        for (const { client } of this.wrapped) {
+            const original = client.__telescopeOriginalSendCommand__;
+            if (original) {
+                client.sendCommand = original;
+                client[PATCHED] = false;
+                client.__telescopeOriginalSendCommand__ = undefined;
+            }
+        }
+        this.wrapped.length = 0;
+    }
+    /** Wrap the ioredis client(s) backing a connection. */
+    instrument(connection) {
+        if (!connection || typeof connection !== 'object')
+            return;
+        const name = typeof connection.connectionName === 'string' ? connection.connectionName : null;
+        this.wrap(connection.ioConnection, name);
+        this.wrap(connection.ioSubscriberConnection, name);
+    }
+    /** Monkey-patch one ioredis client's `sendCommand`. No-op when it lacks the
+     *  method or is already wrapped. */
+    wrap(candidate, connection) {
+        if (!hasSendCommand(candidate))
+            return;
+        const client = candidate;
+        if (client[PATCHED])
+            return;
+        client[PATCHED] = true;
+        const watcher = this;
+        // Keep the EXACT original reference for a clean restore on stop(); call it
+        // with the client as `this` so binding is not baked into what we restore.
+        const original = client.sendCommand;
+        client.__telescopeOriginalSendCommand__ = original;
+        this.wrapped.push({ client, connection });
+        client.sendCommand = function patchedSendCommand(command, ...rest) {
+            const startedAt = now();
+            const result = original.call(client, command, ...rest);
+            if (isThenable(result)) {
+                const finalize = () => {
+                    watcher.record(command, connection, now() - startedAt);
+                };
+                result.then(finalize, finalize);
+            }
+            else {
+                watcher.record(command, connection, null);
+            }
+            return result;
+        };
+    }
+    record(command, connection, durationMs) {
+        safeRecord(buildRedisEntry(command, connection, durationMs), 'RedisWatcher');
+    }
+}
+/** Narrow an arbitrary value to a {@link RedisManagerLike}. */
+function isManager(value) {
+    return typeof value === 'object' && value !== null;
+}
+/** Map a captured Redis command to a telescope {@link RecordInput}. Exported so
+ *  the entry shape can be unit-tested without a real ioredis client. */
+export function buildRedisEntry(command, connection, durationMs) {
+    const name = typeof command.name === 'string' ? command.name.toUpperCase() : String(command.name ?? '');
+    const args = Array.isArray(command.args) ? command.args : [];
+    const traceId = currentTraceId();
+    const content = {
+        command: name,
+        args,
+        connection,
+        durationMs: durationMs === null ? null : Math.max(0, durationMs),
+        traceId,
+    };
+    return {
+        type: EntryType.Redis,
+        familyHash: `redis:${name}`,
+        content,
+        durationMs: content.durationMs,
+        traceId,
+        tags: ['redis', `redis:${name}`, ...(connection ? [`connection:${connection}`] : [])],
+    };
+}
+//# sourceMappingURL=redis_watcher.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redis_watcher.js","sourceRoot":"","sources":["../../../src/watchers/redis_watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2DzC;;0DAE0D;AAC1D,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAQ5D,oEAAoE;AACpE,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,CAAC,aAAa,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3F,OAAO,OAAQ,KAAkC,CAAC,WAAW,KAAK,UAAU,CAAC;AAC/E,CAAC;AAED,qEAAqE;AACrE,SAAS,GAAG;IACV,OAAO,OAAO,WAAW,KAAK,QAAQ,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU;QAC7E,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE;QACnB,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;AACjB,CAAC;AAED,gFAAgF;AAChF,SAAS,UAAU,CAAC,KAAc;IAChC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACf,OAAQ,KAA2B,CAAC,IAAI,KAAK,UAAU,CACxD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,OAAO,YAAY;IACd,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC;IACf,OAAO,CAA0B;IAClD,iFAAiF;IAChE,OAAO,GAAqE,EAAE,CAAC;IACxF,kBAAkB,GAAwB,IAAI,CAAC;IAEvD;8DAC0D;IAC1D,YAAY,OAAgB;QAC1B,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,CAAC;IAED;qBACiB;IACjB,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,IAAI,CAAC,kBAAkB;YAAE,OAAO;QAEpC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC;QAC9C,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YACzC,KAAK,MAAM,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;gBAAE,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QAC9E,CAAC;QAED,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,KAAK,UAAU,EAAE,CAAC;YAC1C,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,UAAU,EAAE,EAAE,CACrE,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,CAC5B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,iFAAiF;IACjF,IAAI;QACF,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;QAC5B,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;QAC/B,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACtC,MAAM,QAAQ,GAAG,MAAM,CAAC,gCAAgC,CAAC;YACzD,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,CAAC,WAAW,GAAG,QAAQ,CAAC;gBAC9B,MAAM,CAAC,OAAO,CAAC,GAAG,KAAK,CAAC;gBACxB,MAAM,CAAC,gCAAgC,GAAG,SAAS,CAAC;YACtD,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,uDAAuD;IAC/C,UAAU,CAAC,UAA+B;QAChD,IAAI,CAAC,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ;YAAE,OAAO;QAC1D,MAAM,IAAI,GAAG,OAAO,UAAU,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9F,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,sBAAsB,EAAE,IAAI,CAAC,CAAC;IACrD,CAAC;IAED;wCACoC;IAC5B,IAAI,CAAC,SAAkB,EAAE,UAAyB;QACxD,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC;YAAE,OAAO;QACvC,MAAM,MAAM,GAAG,SAAS,CAAC;QACzB,IAAI,MAAM,CAAC,OAAO,CAAC;YAAE,OAAO;QAC5B,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;QAEvB,MAAM,OAAO,GAAG,IAAI,CAAC;QACrB,2EAA2E;QAC3E,0EAA0E;QAC1E,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC;QACpC,MAAM,CAAC,gCAAgC,GAAG,QAAQ,CAAC;QACnD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;QAE1C,MAAM,CAAC,WAAW,GAAG,SAAS,kBAAkB,CAE9C,OAAyB,EACzB,GAAG,IAAe;YAElB,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC;YACvD,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvB,MAAM,QAAQ,GAAG,GAAS,EAAE;oBAC1B,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,CAAC;gBACzD,CAAC,CAAC;gBACF,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAClC,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;YAC5C,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC;IAEO,MAAM,CACZ,OAAyB,EACzB,UAAyB,EACzB,UAAyB;QAEzB,UAAU,CAAC,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,cAAc,CAAC,CAAC;IAC/E,CAAC;CACF;AAED,+DAA+D;AAC/D,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED;wEACwE;AACxE,MAAM,UAAU,eAAe,CAC7B,OAAyB,EACzB,UAAyB,EACzB,UAAyB;IAEzB,MAAM,IAAI,GACR,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;IAC7F,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;IACjC,MAAM,OAAO,GAAsB;QACjC,OAAO,EAAE,IAAI;QACb,IAAI;QACJ,UAAU;QACV,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC;QAChE,OAAO;KACR,CAAC;IACF,OAAO;QACL,IAAI,EAAE,SAAS,CAAC,KAAK;QACrB,UAAU,EAAE,SAAS,IAAI,EAAE;QAC3B,OAAO;QACP,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,OAAO;QACP,IAAI,EAAE,CAAC,OAAO,EAAE,SAAS,IAAI,EAAE,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,cAAc,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;KACtF,CAAC;AACJ,CAAC"}

package/dist/stubs/config/telescope.stub

@@ -53,4 +53,13 @@ export default defineConfig({
   //   enabled: true,
   //   keys: ['ssn', 'credit_card'],
   // },
+
+  /**
+   * Live SSE streaming of new entries to the dashboard. ENABLED by default and
+   * zero-overhead while no dashboard is connected. Set `enabled: false` to turn
+   * the `<telescope>/api/stream` endpoint off entirely.
+   */
+  // stream: {
+  //   enabled: true,
+  // },
 })

package/dist/stubs/config/telescope_ui.stub

@@ -37,4 +37,17 @@ export default defineConfig({
   //   token: env.get('TELESCOPE_UI_TOKEN'),
   //   basic: { username: 'admin', password: env.get('TELESCOPE_UI_PASSWORD') },
   // },
+
+  /**
+   * Request REPLAY: re-issue a captured request from the dashboard against the
+   * LOCAL server. DISABLED BY DEFAULT because it re-runs a real request that may
+   * MUTATE state (a captured POST/DELETE runs again). It only ever targets
+   * `127.0.0.1:<port>` (same-origin, never an arbitrary URL) and strips
+   * cookie/authorization/host headers. Enable it knowingly:
+   */
+  // replay: {
+  //   enabled: true,
+  //   // port: 3333,      // defaults to PORT env or 3000
+  //   // timeoutMs: 30000,
+  // },
 })

package/dist/stubs/config/telescope_watchers.stub

@@ -21,10 +21,21 @@ export default defineConfig({
    *  - 'cache'       — records @adonisjs/cache hit/miss/write/delete events.
    *  - 'http-client' — records every outbound fetch call (method, url, status, duration).
    *  - 'logs'        — records AdonisJS logger output (level, message, structured fields).
+   *  - 'queue'       — records @adonisjs/queue job executions (optional peer; engine
+   *                    diagnostics-channel trace). No-op when the peer is absent.
+   *  - 'events'      — records every event emitted through the core Emitter (onAny),
+   *                    with an ignore-list (db:query / mail:sent are excluded by default).
+   *  - 'redis'       — records @adonisjs/redis commands (optional peer; wraps the
+   *                    ioredis sendCommand). No-op when the peer is absent.
    *
-   * Note: the 'mail' and 'cache' event contracts are best-effort — those packages
-   * are not present in this repo, so their event names/payloads could not be
-   * verified against their types. See the package README.
+   * Note: the 'mail' / 'cache' / 'queue' / 'redis' event contracts are best-effort —
+   * those packages are not present in this repo, so their event names/payloads could
+   * not be verified against their types. See the package README.
+   *
+   * There is intentionally NO 'schedule' watcher: AdonisJS ships no first-party
+   * scheduler and community schedulers expose no event/hook surface to tap. In the
+   * Agora ecosystem, @adonis-agora/durable bridges scheduled/cron runs onto the
+   * diagnostics bus, which the diagnostics watcher already records.
    */
   // watchers: ['query'],
 })

package/package.json

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