@adonis-agora/telescope 0.1.0

package/dist/src/watchers/cache_watcher.js

@@ -0,0 +1,72 @@
+import { currentTraceId } from '../context_accessor.js';
+import { EntryType } from '../entry.js';
+import { safeRecord } from './record.js';
+/**
+ * The `@adonisjs/cache` event names this watcher subscribes to, mapped to the
+ * cache operation recorded for each.
+ *
+ * NOTE: `@adonisjs/cache` is not installed in this repository, so these event
+ * names and their payloads could NOT be verified against its types (see this
+ * package's README). They follow `@adonisjs/cache`'s documented `cache:*` event
+ * convention but should be treated as best-effort. The set is exported so a host
+ * can override it if a future version diverges.
+ */
+export const CACHE_EVENTS = {
+    'cache:hit': 'hit',
+    'cache:miss': 'miss',
+    'cache:written': 'write',
+    'cache:deleted': 'delete',
+    'cache:cleared': 'clear',
+};
+/**
+ * Records `@adonisjs/cache` activity as `cache` telescope entries — one per
+ * hit/miss/write/delete/clear event — correlated to the active request via the
+ * trace id.
+ *
+ * Recording is fire-and-forget and fully guarded: a telescope failure can never
+ * break a cache operation.
+ *
+ * @remarks
+ * The event-name → operation map ({@link CACHE_EVENTS}) is best-effort because
+ * `@adonisjs/cache` is not installed in this repo and its event contract could not
+ * be verified. Pass a custom map to the constructor to adapt to your version.
+ */
+export class CacheWatcher {
+    type = EntryType.Cache;
+    events;
+    unsubscribes = [];
+    constructor(events = CACHE_EVENTS) {
+        this.events = events;
+    }
+    start(emitter) {
+        if (this.unsubscribes.length > 0)
+            return;
+        for (const [eventName, operation] of Object.entries(this.events)) {
+            this.unsubscribes.push(emitter.on(eventName, (data) => this.handle(operation, data)));
+        }
+    }
+    stop() {
+        for (const unsubscribe of this.unsubscribes)
+            unsubscribe();
+        this.unsubscribes.length = 0;
+    }
+    handle(operation, data) {
+        const event = data && typeof data === 'object' ? data : {};
+        safeRecord(buildCacheEntry(operation, event), 'CacheWatcher');
+    }
+}
+/** Map a cache operation + payload to a telescope {@link RecordInput}. */
+export function buildCacheEntry(operation, event) {
+    const key = typeof event.key === 'string' ? event.key : null;
+    const store = typeof event.store === 'string' ? event.store : null;
+    const traceId = currentTraceId();
+    const content = { operation, key, store, traceId };
+    return {
+        type: EntryType.Cache,
+        familyHash: key ? `${operation}:${key}` : operation,
+        content,
+        traceId,
+        tags: [`cache:${operation}`, ...(store ? [`store:${store}`] : [])],
+    };
+}
+//# sourceMappingURL=cache_watcher.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache_watcher.js","sourceRoot":"","sources":["../../../src/watchers/cache_watcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAoB,MAAM,aAAa,CAAC;AAE1D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAmC;IAC1D,WAAW,EAAE,KAAK;IAClB,YAAY,EAAE,MAAM;IACpB,eAAe,EAAE,OAAO;IACxB,eAAe,EAAE,QAAQ;IACzB,eAAe,EAAE,OAAO;CACzB,CAAC;AA2BF;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,YAAY;IACd,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC;IACf,MAAM,CAAiC;IACvC,YAAY,GAAsB,EAAE,CAAC;IAEtD,YAAY,SAAyC,YAAY;QAC/D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,OAAoB;QACxB,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO;QACzC,KAAK,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACjE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IAED,IAAI;QACF,KAAK,MAAM,WAAW,IAAI,IAAI,CAAC,YAAY;YAAE,WAAW,EAAE,CAAC;QAC3D,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IAC/B,CAAC;IAEO,MAAM,CAAC,SAAyB,EAAE,IAAa;QACrD,MAAM,KAAK,GAAmB,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAuB,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/F,UAAU,CAAC,eAAe,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,cAAc,CAAC,CAAC;IAChE,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAC7B,SAAyB,EACzB,KAAqB;IAErB,MAAM,GAAG,GAAG,OAAO,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7D,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACnE,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;IACjC,MAAM,OAAO,GAAsB,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACtE,OAAO;QACL,IAAI,EAAE,SAAS,CAAC,KAAK;QACrB,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,SAAS;QACnD,OAAO;QACP,OAAO;QACP,IAAI,EAAE,CAAC,SAAS,SAAS,EAAE,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;KACnE,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,38 @@
+/** The per-technology watchers this package ships. */
+export type WatcherName = 'query' | 'mail' | 'cache' | 'http-client' | 'logs';
+/**
+ * The shape of `config/telescope_watchers.ts`. Everything is optional: by default
+ * only the Lucid `query` watcher is enabled (it is the one whose events are
+ * verified against installed types), with the rest opt-in.
+ */
+export interface TelescopeWatchersConfig {
+    /**
+     * Master switch. When `false`, no per-technology watcher is started. Default
+     * `true`.
+     */
+    enabled?: boolean;
+    /**
+     * Which watchers are active. Omit a name to disable it. Default `['query']`.
+     *  - `'query'` — records every Lucid SQL query (`db:query`).
+     *  - `'mail'`  — records every email sent (`mail:sent`).
+     *  - `'cache'` — records `@adonisjs/cache` hit/miss/write/delete events.
+     *  - `'http-client'` — records every outbound `fetch` call.
+     *  - `'logs'`  — records AdonisJS logger output as `log` entries.
+     */
+    watchers?: WatcherName[];
+}
+/** The fully-resolved watchers config the provider acts on (no optionals). */
+export interface ResolvedTelescopeWatchersConfig {
+    enabled: boolean;
+    watchers: Set<WatcherName>;
+}
+/** The default set of enabled watchers — the verified Lucid query watcher only. */
+export declare const DEFAULT_WATCHERS: WatcherName[];
+/**
+ * Identity helper giving `config/telescope_watchers.ts` full type-checking,
+ * mirroring the AdonisJS `defineConfig` convention.
+ */
+export declare function defineConfig(config: TelescopeWatchersConfig): TelescopeWatchersConfig;
+/** Apply defaults to a (possibly partial) config. */
+export declare function resolveConfig(config?: TelescopeWatchersConfig): ResolvedTelescopeWatchersConfig;
+//# sourceMappingURL=define_config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.d.ts","sourceRoot":"","sources":["../../../src/watchers/define_config.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED,8EAA8E;AAC9E,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;CAC5B;AAED,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,EAAE,WAAW,EAAc,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,uBAAuB,GAAG,uBAAuB,CAErF;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAC3B,MAAM,GAAE,uBAA4B,GACnC,+BAA+B,CAKjC"}

package/dist/src/watchers/define_config.js

@@ -0,0 +1,17 @@
+/** The default set of enabled watchers — the verified Lucid query watcher only. */
+export const DEFAULT_WATCHERS = ['query'];
+/**
+ * Identity helper giving `config/telescope_watchers.ts` full type-checking,
+ * mirroring the AdonisJS `defineConfig` convention.
+ */
+export function defineConfig(config) {
+    return config;
+}
+/** Apply defaults to a (possibly partial) config. */
+export function resolveConfig(config = {}) {
+    return {
+        enabled: config.enabled ?? true,
+        watchers: new Set(config.watchers ?? DEFAULT_WATCHERS),
+    };
+}
+//# sourceMappingURL=define_config.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define_config.js","sourceRoot":"","sources":["../../../src/watchers/define_config.ts"],"names":[],"mappings":"AAgCA,mFAAmF;AACnF,MAAM,CAAC,MAAM,gBAAgB,GAAkB,CAAC,OAAO,CAAC,CAAC;AAEzD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAA+B;IAC1D,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAC3B,SAAkC,EAAE;IAEpC,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;QAC/B,QAAQ,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,gBAAgB,CAAC;KACvD,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,32 @@
+/**
+ * The narrow, structural slice of the AdonisJS event emitter the watchers in this
+ * package depend on. Mirroring the `@adonisjs/events` `Emitter` surface
+ * structurally — rather than importing it — keeps the watchers unit-testable with
+ * a plain double and avoids a hard build-time coupling to a specific emitter
+ * version.
+ *
+ * `on()` returns an unsubscribe function (this is exactly what the real Adonis
+ * emitter, built on `emittery`, returns), which is how every watcher tears down
+ * cleanly on {@link Watcher.stop}.
+ */
+export interface EmitterLike {
+    /**
+     * Subscribe `listener` to `event`. Returns a function that removes that exact
+     * subscription when called.
+     */
+    on(event: string, listener: (data: unknown) => void): () => void;
+}
+/**
+ * The common shape every per-technology watcher implements: start subscribing on
+ * an emitter, and stop (fully unsubscribe) later. Neither method ever throws into
+ * the host application.
+ */
+export interface Watcher {
+    /** The telescope entry `type` this watcher records under. */
+    readonly type: string;
+    /** Begin recording by subscribing to the relevant emitter event(s). */
+    start(emitter: EmitterLike): void;
+    /** Stop recording by removing every subscription this watcher added. */
+    stop(): void;
+}
+//# sourceMappingURL=emitter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../../src/watchers/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAClE;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,wEAAwE;IACxE,IAAI,IAAI,IAAI,CAAC;CACd"}

package/dist/src/watchers/emitter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=emitter.js.map

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

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

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

@@ -0,0 +1,74 @@
+import { type RecordInput } from '../entry.js';
+/** Options for {@link HttpClientWatcher}. */
+export interface HttpClientWatcherOptions {
+    /** Outbound calls at/above this many ms get a `slow` tag. Default 1000. */
+    slowMs?: number;
+    /** Time source; injectable for tests. Default `Date.now`. */
+    clock?: {
+        now(): number;
+    };
+}
+/** The recorded body of an `http-client` entry. */
+export interface HttpClientEntryContent {
+    /** The request method, upper-cased (e.g. `'GET'`). */
+    method: string;
+    /** The sanitized request url (userinfo stripped, sensitive query values masked). */
+    url: string;
+    /** The target host (e.g. `'api.stripe.com'`), or `null` for a relative/invalid url. */
+    host: string | null;
+    /** The response status, or `null` on a transport (network) failure. */
+    statusCode: number | null;
+    /** Wall-clock duration of the call in milliseconds. */
+    durationMs: number;
+    /** The active trace id at call time, or `null`. */
+    traceId: string | null;
+}
+type FetchFn = typeof globalThis.fetch;
+type FetchInit = Parameters<FetchFn>[1];
+/** Mark a `RequestInit` so the {@link HttpClientWatcher} skips recording the
+ *  call it belongs to. Use for telescope's own outbound fetches (remote store,
+ *  alert webhooks) so the watcher never records — or recurses on — itself. */
+export declare function markInternalFetch(init: FetchInit): FetchInit;
+/**
+ * Records every OUTBOUND HTTP call as an `http-client` telescope entry by
+ * wrapping the Node global `fetch`. Each call is timed; method, sanitized url,
+ * host, status and duration are captured and correlated to the active request
+ * via the trace id.
+ *
+ * The wrapper never alters the host's call: it awaits the real `fetch`, records
+ * fire-and-forget (a telescope failure can't break or block the request), and
+ * always re-throws a network error. Telescope's own outbound fetches — marked
+ * via {@link markInternalFetch} — are skipped, so the watcher never records or
+ * recurses on itself.
+ *
+ * Patching the global is idempotent process-wide (a `Symbol.for` marker). Unlike
+ * the emitter watchers, this implements its own lifecycle: `start()` takes no
+ * emitter; `stop()` restores the original `fetch`.
+ */
+export declare class HttpClientWatcher {
+    readonly type: "http-client";
+    private readonly slowMs;
+    private readonly clock;
+    /** Whether THIS instance installed the patch (so only it restores on stop). */
+    private installed;
+    constructor(options?: HttpClientWatcherOptions);
+    /** Patch `globalThis.fetch` to record outbound calls. Idempotent: a second
+     *  call (or another instance / package copy) is a no-op. */
+    start(): void;
+    /** Restore the original `fetch` — but only if THIS instance installed the
+     *  current wrapper (avoids clobbering a wrapper a later instance installed). */
+    stop(): void;
+    /** Build + record an entry, swallowing every failure via {@link safeRecord}. */
+    private record;
+}
+/** Map a captured outbound call to a telescope {@link RecordInput}. Exported so
+ *  the entry shape can be unit-tested without patching the global. */
+export declare function buildHttpClientEntry(call: {
+    method: string;
+    url: string;
+    host: string | null;
+    statusCode: number | null;
+    durationMs: number;
+}, slowMs?: number): RecordInput<HttpClientEntryContent>;
+export {};
+//# sourceMappingURL=http_client_watcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http_client_watcher.d.ts","sourceRoot":"","sources":["../../../src/watchers/http_client_watcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAI1D,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,CAAC,EAAE;QAAE,GAAG,IAAI,MAAM,CAAA;KAAE,CAAC;CAC3B;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uEAAuE;IACvE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAsBD,KAAK,OAAO,GAAG,OAAO,UAAU,CAAC,KAAK,CAAC;AAEvC,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;AA+CxC;;8EAE8E;AAC9E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAI5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAiB;IAC5B,QAAQ,CAAC,IAAI,gBAAwB;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,+EAA+E;IAC/E,OAAO,CAAC,SAAS,CAAS;gBAEd,OAAO,GAAE,wBAA6B;IAKlD;gEAC4D;IAC5D,KAAK,IAAI,IAAI;IAkCb;oFACgF;IAChF,IAAI,IAAI,IAAI;IASZ,gFAAgF;IAChF,OAAO,CAAC,MAAM;CAYf;AAED;sEACsE;AACtE,wBAAgB,oBAAoB,CAClC,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB,EACD,MAAM,SAAkB,GACvB,WAAW,CAAC,sBAAsB,CAAC,CAwBrC"}

package/dist/src/watchers/http_client_watcher.js

@@ -0,0 +1,168 @@
+import { currentTraceId } from '../context_accessor.js';
+import { EntryType } from '../entry.js';
+import { normalizeHttpTarget } from './normalize_http_target.js';
+import { safeRecord } from './record.js';
+/** Default slow-call threshold in milliseconds. */
+const DEFAULT_SLOW_MS = 1000;
+/** Query-param keys whose VALUES are masked from a captured URL. Key-based
+ *  content redaction can't reach a URL string leaf, so we sanitize the URL here
+ *  before it ever reaches the (separately redacted) entry content. */
+const SENSITIVE_PARAM = /(token|secret|password|passwd|api[-_]?key|access[-_]?key|auth|credential)/i;
+const REDACTED = '[REDACTED]';
+/** Marks our wrapper so the global `fetch` is patched exactly once even if two
+ *  copies of this package load. `Symbol.for` (the global registry) is deliberate:
+ *  both copies resolve the same marker and neither double-wraps the other. */
+const PATCHED = Symbol.for('@agora/telescope:httpClientPatched');
+/** Marks an `init` (RequestInit) as telescope's OWN outbound call so the wrapper
+ *  skips recording it — the recursion guard for any internal fetch (e.g. a
+ *  future remote store / alert webhook performing a `fetch`). */
+const INTERNAL = Symbol.for('@agora/telescope:internalFetch');
+/**
+ * Sanitize a raw URL for storage: strip userinfo (`user:pass@`) and mask
+ * sensitive query-param VALUES, returning `{ url, host }`. A relative/invalid
+ * url is kept verbatim with `host: null`.
+ */
+function sanitizeUrl(rawUrl) {
+    try {
+        const parsed = new URL(rawUrl);
+        const host = parsed.host;
+        parsed.username = '';
+        parsed.password = '';
+        for (const key of [...parsed.searchParams.keys()]) {
+            if (SENSITIVE_PARAM.test(key))
+                parsed.searchParams.set(key, REDACTED);
+        }
+        return { url: parsed.toString(), host };
+    }
+    catch {
+        return { url: rawUrl, host: null };
+    }
+}
+/** Pull method/url/host out of fetch's `(input, init)` without throwing. */
+function describeRequest(input, init) {
+    let rawUrl = '';
+    let method = 'GET';
+    if (typeof input === 'string')
+        rawUrl = input;
+    else if (input instanceof URL)
+        rawUrl = input.href;
+    else if (input instanceof Request) {
+        rawUrl = input.url;
+        method = input.method;
+    }
+    if (init && typeof init.method === 'string')
+        method = init.method;
+    const { url, host } = sanitizeUrl(rawUrl);
+    return { method: method.toUpperCase(), url, host };
+}
+/** Mark a `RequestInit` so the {@link HttpClientWatcher} skips recording the
+ *  call it belongs to. Use for telescope's own outbound fetches (remote store,
+ *  alert webhooks) so the watcher never records — or recurses on — itself. */
+export function markInternalFetch(init) {
+    const next = (init ?? {});
+    next[INTERNAL] = true;
+    return next;
+}
+/**
+ * Records every OUTBOUND HTTP call as an `http-client` telescope entry by
+ * wrapping the Node global `fetch`. Each call is timed; method, sanitized url,
+ * host, status and duration are captured and correlated to the active request
+ * via the trace id.
+ *
+ * The wrapper never alters the host's call: it awaits the real `fetch`, records
+ * fire-and-forget (a telescope failure can't break or block the request), and
+ * always re-throws a network error. Telescope's own outbound fetches — marked
+ * via {@link markInternalFetch} — are skipped, so the watcher never records or
+ * recurses on itself.
+ *
+ * Patching the global is idempotent process-wide (a `Symbol.for` marker). Unlike
+ * the emitter watchers, this implements its own lifecycle: `start()` takes no
+ * emitter; `stop()` restores the original `fetch`.
+ */
+export class HttpClientWatcher {
+    type = EntryType.HttpClient;
+    slowMs;
+    clock;
+    /** Whether THIS instance installed the patch (so only it restores on stop). */
+    installed = false;
+    constructor(options = {}) {
+        this.slowMs = options.slowMs ?? DEFAULT_SLOW_MS;
+        this.clock = options.clock ?? { now: () => Date.now() };
+    }
+    /** Patch `globalThis.fetch` to record outbound calls. Idempotent: a second
+     *  call (or another instance / package copy) is a no-op. */
+    start() {
+        const current = globalThis.fetch;
+        if (typeof current !== 'function' || current[PATCHED])
+            return;
+        const original = current;
+        const watcher = this;
+        const patched = async function patchedFetch(input, init) {
+            // Skip (and don't record) telescope's own outbound calls — the recursion
+            // guard for any internal fetch.
+            if (init && init[INTERNAL]) {
+                return original(input, init);
+            }
+            const startedAt = watcher.clock.now();
+            const { method, url, host } = describeRequest(input, init);
+            try {
+                const response = await original(input, init);
+                watcher.record(method, url, host, response.status, watcher.clock.now() - startedAt);
+                return response;
+            }
+            catch (error) {
+                watcher.record(method, url, host, null, watcher.clock.now() - startedAt);
+                throw error; // never swallow the host's network error
+            }
+        };
+        patched[PATCHED] = true;
+        patched.__telescopeOriginal__ = original;
+        globalThis.fetch = patched;
+        this.installed = true;
+    }
+    /** Restore the original `fetch` — but only if THIS instance installed the
+     *  current wrapper (avoids clobbering a wrapper a later instance installed). */
+    stop() {
+        if (!this.installed)
+            return;
+        this.installed = false;
+        const current = globalThis.fetch;
+        if (current?.[PATCHED] && current.__telescopeOriginal__) {
+            globalThis.fetch = current.__telescopeOriginal__;
+        }
+    }
+    /** Build + record an entry, swallowing every failure via {@link safeRecord}. */
+    record(method, url, host, statusCode, durationMs) {
+        safeRecord(buildHttpClientEntry({ method, url, host, statusCode, durationMs }, this.slowMs), 'HttpClientWatcher');
+    }
+}
+/** Map a captured outbound call to a telescope {@link RecordInput}. Exported so
+ *  the entry shape can be unit-tested without patching the global. */
+export function buildHttpClientEntry(call, slowMs = DEFAULT_SLOW_MS) {
+    const traceId = currentTraceId();
+    const content = {
+        method: call.method,
+        url: call.url,
+        host: call.host,
+        statusCode: call.statusCode,
+        durationMs: Math.max(0, call.durationMs),
+        traceId,
+    };
+    const tags = ['http-client'];
+    if (content.host)
+        tags.push(`host:${content.host}`);
+    // A 4xx is a valid response, not a transport failure — only 5xx / network errors are 'failed'.
+    if (content.statusCode === null || content.statusCode >= 500)
+        tags.push('failed');
+    if (content.durationMs >= slowMs)
+        tags.push('slow');
+    return {
+        type: EntryType.HttpClient,
+        familyHash: normalizeHttpTarget(content.method, content.url),
+        content,
+        durationMs: content.durationMs,
+        traceId,
+        tags,
+    };
+}
+//# sourceMappingURL=http_client_watcher.js.map

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

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

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

@@ -0,0 +1,19 @@
+/** Keep in sync with this package's `version` in package.json. */
+export declare const VERSION = "0.1.0";
+export type { EmitterLike, Watcher } from './emitter.js';
+export { resolveStore, safeRecord } from './record.js';
+export { buildQueryEntry, DB_QUERY_EVENT, LucidQueryWatcher } from './lucid_query_watcher.js';
+export type { DbQueryEventLike, QueryEntryContent } from './lucid_query_watcher.js';
+export { queryFamilyHash } from './query_family_hash.js';
+export { buildMailEntry, MAIL_SENT_EVENT, MailWatcher } from './mail_watcher.js';
+export type { MailEntryContent, MailSentEventLike } from './mail_watcher.js';
+export { buildCacheEntry, CACHE_EVENTS, CacheWatcher } from './cache_watcher.js';
+export type { CacheEntryContent, CacheEventLike, CacheOperation } from './cache_watcher.js';
+export { buildHttpClientEntry, HttpClientWatcher, markInternalFetch, } from './http_client_watcher.js';
+export type { HttpClientEntryContent, HttpClientWatcherOptions, } from './http_client_watcher.js';
+export { normalizeHttpTarget } from './normalize_http_target.js';
+export { buildLogEntry, extractLog, LOG_LEVELS, LogsWatcher } from './logs_watcher.js';
+export type { LogEntryContent, LoggerLike, LogLevel, LogsWatcherOptions, } from './logs_watcher.js';
+export { DEFAULT_WATCHERS, defineConfig, resolveConfig, } from './define_config.js';
+export type { ResolvedTelescopeWatchersConfig, TelescopeWatchersConfig, WatcherName, } from './define_config.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/watchers/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC9F,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACjF,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAG7E,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjF,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAG5F,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGjE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACvF,YAAY,EACV,eAAe,EACf,UAAU,EACV,QAAQ,EACR,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,+BAA+B,EAC/B,uBAAuB,EACvB,WAAW,GACZ,MAAM,oBAAoB,CAAC"}

package/dist/src/watchers/index.js

@@ -0,0 +1,19 @@
+/** Keep in sync with this package's `version` in package.json. */
+export const VERSION = '0.1.0';
+// — runtime recording (advanced) —
+export { resolveStore, safeRecord } from './record.js';
+// — Lucid query watcher (the headline watcher) —
+export { buildQueryEntry, DB_QUERY_EVENT, LucidQueryWatcher } from './lucid_query_watcher.js';
+export { queryFamilyHash } from './query_family_hash.js';
+// — mail watcher —
+export { buildMailEntry, MAIL_SENT_EVENT, MailWatcher } from './mail_watcher.js';
+// — cache watcher —
+export { buildCacheEntry, CACHE_EVENTS, CacheWatcher } from './cache_watcher.js';
+// — http-client (outbound) watcher —
+export { buildHttpClientEntry, HttpClientWatcher, markInternalFetch, } from './http_client_watcher.js';
+export { normalizeHttpTarget } from './normalize_http_target.js';
+// — logs watcher —
+export { buildLogEntry, extractLog, LOG_LEVELS, LogsWatcher } from './logs_watcher.js';
+// — config —
+export { DEFAULT_WATCHERS, defineConfig, resolveConfig, } from './define_config.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/watchers/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAK/B,mCAAmC;AACnC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvD,iDAAiD;AACjD,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE9F,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,mBAAmB;AACnB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGjF,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGjF,qCAAqC;AACrC,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAKlC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,mBAAmB;AACnB,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQvF,aAAa;AACb,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,aAAa,GACd,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,82 @@
+import { type RecordInput } from '../entry.js';
+/** The standard pino/AdonisJS log levels this watcher tees, lowest → highest. */
+export declare const LOG_LEVELS: readonly ["trace", "debug", "info", "warn", "error", "fatal"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+/** A single pino-style log method: either `(message, ...values)` or
+ *  `(mergingObject, message?, ...values)`. We read only the message string and a
+ *  bounded slice of the merging object. */
+type LogMethod = (...args: unknown[]) => void;
+/**
+ * The structural slice of the AdonisJS `Logger` (`@adonisjs/logger`) this watcher
+ * taps — the level methods. Mirrored structurally (rather than importing the
+ * class) so the watcher stays unit-testable with a plain double and has no
+ * build-time coupling to a specific logger version.
+ */
+export type LoggerLike = {
+    [Level in LogLevel]?: LogMethod;
+};
+/** The recorded body of a `log` entry. */
+export interface LogEntryContent {
+    /** The log level (`'info'`, `'error'`, …). */
+    level: LogLevel;
+    /** The log message string, or `null` when the call carried only an object. */
+    message: string | null;
+    /** A bounded copy of the merging object's fields, or `null`. Redacted centrally. */
+    context: Record<string, unknown> | null;
+    /** The active trace id at log time, or `null`. */
+    traceId: string | null;
+}
+/** Options for {@link LogsWatcher}. */
+export interface LogsWatcherOptions {
+    /** Only record at/above this level. Default `'trace'` (record everything). */
+    minLevel?: LogLevel;
+    /** Extra tags appended to every recorded log entry. */
+    tags?: readonly string[];
+}
+/**
+ * Records AdonisJS `Logger` output as `EntryType.Log` entries, correlated to the
+ * active request via the trace id.
+ *
+ * ## How it taps the logger (non-invasive, reversible)
+ * Rather than monkey-patching a global or a prototype, `start(logger)` tees the
+ * level methods on the ONE logger instance resolved from the container. Each teed
+ * method calls the original first (host output is untouched) and then records.
+ * `stop()` restores the originals, so the tap fully unwinds on shutdown.
+ *
+ * Pino has no supported post-construction transport/hook for a live instance, so
+ * instance-scoped method-teeing is the least-invasive option that captures logs
+ * written through the app logger without owning its construction. The tee is
+ * idempotent per instance (a `Symbol.for` marker) and a reentrancy guard prevents
+ * an infinite record→log loop.
+ *
+ * Recording is fire-and-forget and fully guarded — a telescope failure can never
+ * break the host's logging.
+ */
+export declare class LogsWatcher {
+    readonly type: "log";
+    private readonly minLevelIndex;
+    private readonly extraTags;
+    private logger;
+    constructor(options?: LogsWatcherOptions);
+    /** Tee the level methods on `logger`. Idempotent per instance. */
+    start(logger: LoggerLike): void;
+    /** Restore the original level methods on the tapped instance. */
+    stop(): void;
+    /** Build + record a log entry from the level method's arguments. */
+    private record;
+}
+/**
+ * Parse a pino-style level call into `{ message, context }`, mirroring pino's own
+ * argument convention: either `(message, ...)` or `(mergingObject, message?, ...)`.
+ * The context object is shallow-copied and bounded to a handful of keys here; the
+ * central redaction layer scrubs any sensitive values before storage.
+ */
+export declare function extractLog(args: unknown[]): {
+    message: string | null;
+    context: Record<string, unknown> | null;
+};
+/** Map a level + raw method args to a telescope {@link RecordInput}. Exported so
+ *  the entry shape can be unit-tested without teeing a logger. */
+export declare function buildLogEntry(level: LogLevel, args: unknown[], extraTags?: readonly string[]): RecordInput<LogEntryContent>;
+export {};
+//# sourceMappingURL=logs_watcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logs_watcher.d.ts","sourceRoot":"","sources":["../../../src/watchers/logs_watcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1D,iFAAiF;AACjF,eAAO,MAAM,UAAU,+DAAgE,CAAC;AACxF,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD;;2CAE2C;AAC3C,KAAK,SAAS,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;KACtB,KAAK,IAAI,QAAQ,CAAC,CAAC,EAAE,SAAS;CAChC,CAAC;AAEF,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,KAAK,EAAE,QAAQ,CAAC;IAChB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxC,kDAAkD;IAClD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,uDAAuD;IACvD,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAkBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,IAAI,QAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,MAAM,CAA2B;gBAE7B,OAAO,GAAE,kBAAuB;IAK5C,kEAAkE;IAClE,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAgC/B,iEAAiE;IACjE,IAAI,IAAI,IAAI;IAYZ,oEAAoE;IACpE,OAAO,CAAC,MAAM;CAGf;AAUD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG;IAC3C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzC,CAQA;AAeD;kEACkE;AAClE,wBAAgB,aAAa,CAC3B,KAAK,EAAE,QAAQ,EACf,IAAI,EAAE,OAAO,EAAE,EACf,SAAS,GAAE,SAAS,MAAM,EAAO,GAChC,WAAW,CAAC,eAAe,CAAC,CAW9B"}