@adonis-agora/telescope 0.3.3 → 0.5.0

package/dist/src/watchers/lucid_query_watcher.js

@@ -4,6 +4,10 @@ import { queryFamilyHash } from './query_family_hash.js';
 import { safeRecord } from './record.js';
 /** The Lucid event name this watcher subscribes to. */
 export const DB_QUERY_EVENT = 'db:query';
+/** Placeholder a bound value is replaced with when `captureBindings` is off. */
+const REDACTED = '[REDACTED]';
+/** Default slow-query threshold (ms), mirrored from the resolved watcher config. */
+const DEFAULT_SLOW_MS = 500;
 /** Convert a `process.hrtime()` `[seconds, nanoseconds]` tuple to milliseconds. */
 function hrtimeToMs(duration) {
     if (!Array.isArray(duration) || duration.length !== 2)
@@ -38,6 +42,16 @@ function isDbQueryEvent(data) {
 export class LucidQueryWatcher {
     type = EntryType.Query;
     unsubscribe = null;
+    slowMs;
+    captureBindings;
+    ignoreConnections;
+    normalize;
+    constructor(options = {}) {
+        this.slowMs = options.slowMs ?? DEFAULT_SLOW_MS;
+        this.captureBindings = options.captureBindings ?? false;
+        this.ignoreConnections = new Set((options.ignoreConnections ?? []).map((name) => name.toLowerCase()));
+        this.normalize = options.normalize ?? true;
+    }
     start(emitter) {
         if (this.unsubscribe)
             return;
@@ -51,34 +65,54 @@ export class LucidQueryWatcher {
     handle(data) {
         if (!isDbQueryEvent(data))
             return;
-        safeRecord(buildQueryEntry(data), 'LucidQueryWatcher');
+        // An ignored connection is dropped before any work — a telescope query that
+        // hits the store's own DB, a replica used only for the timeline, etc.
+        if (this.ignoreConnections.has(data.connection.toLowerCase()))
+            return;
+        safeRecord(buildQueryEntry(data, {
+            slowMs: this.slowMs,
+            captureBindings: this.captureBindings,
+            normalize: this.normalize,
+        }), 'LucidQueryWatcher');
     }
 }
-/** Map a Lucid `db:query` payload to a telescope {@link RecordInput}. */
-export function buildQueryEntry(event) {
+/** Map a Lucid `db:query` payload to a telescope {@link RecordInput}. Exported so
+ *  the entry shape can be unit-tested without a running emitter. */
+export function buildQueryEntry(event, options = {}) {
+    const slowMs = options.slowMs ?? DEFAULT_SLOW_MS;
+    const captureBindings = options.captureBindings ?? false;
+    const normalize = options.normalize ?? true;
     const durationMs = hrtimeToMs(event.duration);
     const method = typeof event.method === 'string' ? event.method : null;
     const traceId = currentTraceId();
+    const rawBindings = Array.isArray(event.bindings) ? event.bindings : [];
     const content = {
         sql: event.sql,
-        bindings: Array.isArray(event.bindings) ? event.bindings : [],
+        // Redact bound VALUES by default (they carry PII/secrets) while preserving
+        // arity, so the query's shape stays visible without leaking data.
+        bindings: captureBindings ? rawBindings : rawBindings.map(() => REDACTED),
         durationMs,
         connection: event.connection,
         method,
         inTransaction: typeof event.inTransaction === 'boolean' ? event.inTransaction : null,
         traceId,
     };
+    const tags = [
+        `connection:${event.connection}`,
+        ...(method ? [`method:${method}`] : []),
+        ...(event.model ? [`model:${event.model}`] : []),
+    ];
+    if (durationMs !== null && durationMs >= slowMs)
+        tags.push('slow');
     return {
         type: EntryType.Query,
-        familyHash: queryFamilyHash(event.sql),
+        // Group by SQL template (see queryFamilyHash) so "the same query" rolls up
+        // for the Pulse slow-query + N+1 cards. `normalize: false` hashes verbatim.
+        familyHash: normalize ? queryFamilyHash(event.sql) : queryFamilyHash(event.sql, false),
         content,
         durationMs,
         traceId,
-        tags: [
-            `connection:${event.connection}`,
-            ...(method ? [`method:${method}`] : []),
-            ...(event.model ? [`model:${event.model}`] : []),
-        ],
+        tags,
     };
 }
 //# sourceMappingURL=lucid_query_watcher.js.map

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

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

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

@@ -0,0 +1,144 @@
+import { type RecordInput } from '../entry.js';
+/** The `type` of the entries this watcher records. */
+export declare const PROFILE_ENTRY_TYPE: "profile";
+/** The terminal outcome of a profiling span. */
+export type ProfileStatus = 'completed' | 'failed';
+/** A timing mark taken inside a span, offset (ms) from the span's start. */
+export interface ProfileMark {
+    /** The mark label, e.g. `'validated'`, `'db-loaded'`. */
+    label: string;
+    /** Milliseconds elapsed from the span's start when the mark was taken. */
+    atMs: number;
+}
+/** The recorded body of a `profile` entry. */
+export interface ProfileEntryContent {
+    /** The span label, e.g. `'checkout'`. */
+    label: string;
+    /** Total wall-clock duration of the span in milliseconds. */
+    durationMs: number;
+    /** The span outcome. */
+    status: ProfileStatus;
+    /** In-order timing marks taken inside the span (nested checkpoints). */
+    marks: ProfileMark[];
+    /** The failure message when `status` is `'failed'`, else `null`. */
+    failureReason: string | null;
+    /** The active trace id at record time, or `null`. */
+    traceId: string | null;
+}
+/** Options for {@link ProfilingWatcher}. */
+export interface ProfilingWatcherOptions {
+    /** Spans at/above this many ms get a `slow` tag. Default 100. */
+    slowMs?: number;
+    /**
+     * Spans whose duration is below this are discarded (too short to be worth a
+     * timeline entry). Default `0` (keep all).
+     */
+    minDurationMs?: number;
+    /** Time source; injectable for tests. Default `Date.now`. */
+    clock?: {
+        now(): number;
+    };
+}
+/**
+ * An in-flight profiling span. Add {@link mark}s inside the timed section, then
+ * call {@link end} (or {@link fail}) exactly once to record it. Recording is
+ * fire-and-forget and fully guarded — a telescope failure can never break the
+ * code being profiled.
+ */
+export interface ProfileSession {
+    /** Take a timing mark at the current instant (offset from the span's start). */
+    mark(label: string): this;
+    /** Finish the span and record it as `completed`. Idempotent. */
+    end(): void;
+    /** Finish the span and record it as `failed` with the given error. Idempotent. */
+    fail(error: unknown): void;
+}
+/** A completed span handed to {@link buildProfileEntry}. */
+export interface CompletedProfile {
+    label: string;
+    durationMs: number;
+    status: ProfileStatus;
+    marks: ProfileMark[];
+    error?: unknown;
+}
+/**
+ * Records user-instrumented profiling spans as `profile` telescope entries — one
+ * per timed code section, capturing its label, total duration, in-span timing
+ * marks, and outcome (completed/failed), correlated to the active trace.
+ *
+ * ## How it works
+ * Unlike the emitter-driven watchers, profiling is DRIVEN BY THE USER: there is
+ * no event to tap. Wrap a code section with {@link profile} (or bracket it with
+ * {@link startProfile} + {@link ProfileSession.end}); the watcher times it and
+ * records one entry. It never monkey-patches anything and carries no cost while
+ * disabled — the standalone helpers are a no-op until the provider calls
+ * {@link start}.
+ *
+ * Each entry carries `familyHash` (the label) and `durationMs`, so repeated spans
+ * of the same label roll up and feed the slow-hotspot metrics cards. Recording is
+ * fire-and-forget and fully guarded: a telescope failure can never break the code
+ * being profiled.
+ *
+ * Idiomatic Adonis: a plain class, no DI decorators. The provider constructs it
+ * from `config/telescope_watchers.ts` and calls {@link start} to publish it as the
+ * default backing the bare {@link profile} / {@link startProfile} helpers;
+ * {@link stop} unpublishes.
+ */
+export declare class ProfilingWatcher {
+    readonly type: "profile";
+    private readonly slowMs;
+    private readonly minDurationMs;
+    private readonly clock;
+    constructor(options?: ProfilingWatcherOptions);
+    /** The watcher's time source (used by its sessions). */
+    now(): number;
+    /** Publish this configured instance as the default the standalone
+     *  {@link profile} / {@link startProfile} helpers inherit. Does NOT patch any
+     *  global. Named `start`/`stop` to match the other watchers' provider lifecycle. */
+    start(): void;
+    /** Unpublish this instance as the default (if it is). Never touches globals. */
+    stop(): void;
+    /** Begin a profiling span. Add marks on the returned session, then `end()`/`fail()`. */
+    startProfile(label: string): ProfileSession;
+    /**
+     * Time `fn` as a profiling span. The span's session is passed to `fn` so it can
+     * add timing marks. Records `completed` on return / resolve and `failed` on
+     * throw / reject, always re-throwing so the caller's control flow is untouched.
+     * Works with sync and async `fn`.
+     */
+    profile<T>(label: string, fn: (session: ProfileSession) => T): T;
+    /** Record one already-completed span. Spans below `minDurationMs` are dropped;
+     *  recording is fire-and-forget and never throws. */
+    record(profile: CompletedProfile): void;
+}
+/** Map a completed span to a telescope {@link RecordInput}. Exported so the entry
+ *  shape can be unit-tested without a live watcher. */
+export declare function buildProfileEntry(profile: CompletedProfile, slowMs?: number): RecordInput<ProfileEntryContent>;
+/**
+ * Begin a profiling span through the provider-published default watcher. Returns a
+ * NO-OP session (nothing recorded) when the profiling watcher is not enabled, so
+ * this is safe to leave in code unconditionally.
+ *
+ * @example
+ *   import { startProfile } from '@adonis-agora/telescope/watchers'
+ *   const span = startProfile('checkout')
+ *   // ... work ...
+ *   span.mark('validated')
+ *   // ... more work ...
+ *   span.end()
+ */
+export declare function startProfile(label: string): ProfileSession;
+/**
+ * Time `fn` as a profiling span through the provider-published default watcher.
+ * A no-op passthrough (just runs `fn`) when the profiling watcher is not enabled.
+ *
+ * @example
+ *   import { profile } from '@adonis-agora/telescope/watchers'
+ *   const order = await profile('checkout', async (span) => {
+ *     const cart = await loadCart()
+ *     span.mark('cart-loaded')
+ *     return placeOrder(cart)
+ *   })
+ */
+export declare function profile<T>(label: string, fn: (session: ProfileSession) => T): T;
+//# sourceMappingURL=profiling_watcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profiling_watcher.d.ts","sourceRoot":"","sources":["../../../src/watchers/profiling_watcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAG1D,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,WAAoB,CAAC;AAEpD,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEnD,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,wEAAwE;IACxE,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,oEAAoE;IACpE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qDAAqD;IACrD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,KAAK,CAAC,EAAE;QAAE,GAAG,IAAI,MAAM,CAAA;KAAE,CAAC;CAC3B;AAKD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gEAAgE;IAChE,GAAG,IAAI,IAAI,CAAC;IACZ,kFAAkF;IAClF,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAiDD,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAoBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,IAAI,YAAqB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;gBAE9B,OAAO,GAAE,uBAA4B;IAMjD,wDAAwD;IACxD,GAAG,IAAI,MAAM;IAIb;;wFAEoF;IACpF,KAAK,IAAI,IAAI;IAIb,gFAAgF;IAChF,IAAI,IAAI,IAAI;IAIZ,wFAAwF;IACxF,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc;IAI3C;;;;;OAKG;IACH,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,CAAC,GAAG,CAAC;IAyBhE;yDACqD;IACrD,MAAM,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;CAIxC;AAWD;uDACuD;AACvD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,gBAAgB,EACzB,MAAM,SAAkB,GACvB,WAAW,CAAC,mBAAmB,CAAC,CA4BlC;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAG1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,CAAC,GAAG,CAAC,CAI/E"}

package/dist/src/watchers/profiling_watcher.js

@@ -0,0 +1,231 @@
+import { currentTraceId } from '../context_accessor.js';
+import { EntryType } from '../entry.js';
+import { safeRecord } from './record.js';
+/** The `type` of the entries this watcher records. */
+export const PROFILE_ENTRY_TYPE = EntryType.Profile;
+/** Default slow-span threshold in milliseconds. */
+const DEFAULT_SLOW_MS = 100;
+/** A no-op session returned when profiling is not enabled — zero recording cost. */
+const NOOP_SESSION = {
+    mark() {
+        return this;
+    },
+    end() { },
+    fail() { },
+};
+/** The live session backed by a configured watcher. */
+class ActiveProfileSession {
+    watcher;
+    label;
+    startedAt;
+    marks = [];
+    settled = false;
+    constructor(watcher, label, startedAt) {
+        this.watcher = watcher;
+        this.label = label;
+        this.startedAt = startedAt;
+    }
+    mark(label) {
+        if (this.settled)
+            return this;
+        this.marks.push({ label, atMs: Math.max(0, this.watcher.now() - this.startedAt) });
+        return this;
+    }
+    end() {
+        this.settle('completed', undefined);
+    }
+    fail(error) {
+        this.settle('failed', error);
+    }
+    settle(status, error) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.watcher.record({
+            label: this.label,
+            durationMs: Math.max(0, this.watcher.now() - this.startedAt),
+            status,
+            marks: this.marks,
+            error,
+        });
+    }
+}
+/**
+ * Cross-copy-stable slot holding the provider-configured default watcher, so the
+ * standalone {@link profile} / {@link startProfile} helpers inherit the app's
+ * configured `slowMs` / `minDurationMs` — and, crucially, are a NO-OP until the
+ * provider starts the watcher (profiling stays strictly opt-in). A `Symbol.for`
+ * global slot keeps two copies of this package in agreement, mirroring the
+ * http-client watcher's default-slot stance.
+ */
+const DEFAULT_SLOT = Symbol.for('@agora/telescope:defaultProfilingWatcher');
+const slotHost = globalThis;
+function setDefaultProfilingWatcher(watcher) {
+    slotHost[DEFAULT_SLOT] = watcher;
+}
+function getDefaultProfilingWatcher() {
+    return slotHost[DEFAULT_SLOT] ?? null;
+}
+/**
+ * Records user-instrumented profiling spans as `profile` telescope entries — one
+ * per timed code section, capturing its label, total duration, in-span timing
+ * marks, and outcome (completed/failed), correlated to the active trace.
+ *
+ * ## How it works
+ * Unlike the emitter-driven watchers, profiling is DRIVEN BY THE USER: there is
+ * no event to tap. Wrap a code section with {@link profile} (or bracket it with
+ * {@link startProfile} + {@link ProfileSession.end}); the watcher times it and
+ * records one entry. It never monkey-patches anything and carries no cost while
+ * disabled — the standalone helpers are a no-op until the provider calls
+ * {@link start}.
+ *
+ * Each entry carries `familyHash` (the label) and `durationMs`, so repeated spans
+ * of the same label roll up and feed the slow-hotspot metrics cards. Recording is
+ * fire-and-forget and fully guarded: a telescope failure can never break the code
+ * being profiled.
+ *
+ * Idiomatic Adonis: a plain class, no DI decorators. The provider constructs it
+ * from `config/telescope_watchers.ts` and calls {@link start} to publish it as the
+ * default backing the bare {@link profile} / {@link startProfile} helpers;
+ * {@link stop} unpublishes.
+ */
+export class ProfilingWatcher {
+    type = EntryType.Profile;
+    slowMs;
+    minDurationMs;
+    clock;
+    constructor(options = {}) {
+        this.slowMs = options.slowMs ?? DEFAULT_SLOW_MS;
+        this.minDurationMs = Math.max(0, options.minDurationMs ?? 0);
+        this.clock = options.clock ?? { now: () => Date.now() };
+    }
+    /** The watcher's time source (used by its sessions). */
+    now() {
+        return this.clock.now();
+    }
+    /** Publish this configured instance as the default the standalone
+     *  {@link profile} / {@link startProfile} helpers inherit. Does NOT patch any
+     *  global. Named `start`/`stop` to match the other watchers' provider lifecycle. */
+    start() {
+        setDefaultProfilingWatcher(this);
+    }
+    /** Unpublish this instance as the default (if it is). Never touches globals. */
+    stop() {
+        if (getDefaultProfilingWatcher() === this)
+            setDefaultProfilingWatcher(null);
+    }
+    /** Begin a profiling span. Add marks on the returned session, then `end()`/`fail()`. */
+    startProfile(label) {
+        return new ActiveProfileSession(this, label, this.clock.now());
+    }
+    /**
+     * Time `fn` as a profiling span. The span's session is passed to `fn` so it can
+     * add timing marks. Records `completed` on return / resolve and `failed` on
+     * throw / reject, always re-throwing so the caller's control flow is untouched.
+     * Works with sync and async `fn`.
+     */
+    profile(label, fn) {
+        const session = this.startProfile(label);
+        let result;
+        try {
+            result = fn(session);
+        }
+        catch (error) {
+            session.fail(error);
+            throw error;
+        }
+        if (isPromiseLike(result)) {
+            return result.then((value) => {
+                session.end();
+                return value;
+            }, (error) => {
+                session.fail(error);
+                throw error;
+            });
+        }
+        session.end();
+        return result;
+    }
+    /** Record one already-completed span. Spans below `minDurationMs` are dropped;
+     *  recording is fire-and-forget and never throws. */
+    record(profile) {
+        if (profile.durationMs < this.minDurationMs)
+            return;
+        safeRecord(buildProfileEntry(profile, this.slowMs), 'ProfilingWatcher');
+    }
+}
+/** Narrow a value to a thenable so async `fn`s are awaited without importing a Promise type. */
+function isPromiseLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.then === 'function');
+}
+/** Map a completed span to a telescope {@link RecordInput}. Exported so the entry
+ *  shape can be unit-tested without a live watcher. */
+export function buildProfileEntry(profile, slowMs = DEFAULT_SLOW_MS) {
+    const durationMs = Math.max(0, profile.durationMs);
+    const failed = profile.status === 'failed';
+    const failureReason = failed && profile.error !== undefined ? errorMessage(profile.error) : null;
+    const traceId = currentTraceId();
+    const content = {
+        label: profile.label,
+        durationMs,
+        status: profile.status,
+        marks: profile.marks,
+        failureReason,
+        traceId,
+    };
+    const tags = ['profile', `profile:${profile.label}`];
+    if (failed)
+        tags.push('failed');
+    if (durationMs >= slowMs)
+        tags.push('slow');
+    return {
+        type: EntryType.Profile,
+        // Group by label so every run of the same span rolls up — the slow-hotspot key.
+        familyHash: `profile:${profile.label}`,
+        content,
+        durationMs,
+        traceId,
+        tags,
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Begin a profiling span through the provider-published default watcher. Returns a
+ * NO-OP session (nothing recorded) when the profiling watcher is not enabled, so
+ * this is safe to leave in code unconditionally.
+ *
+ * @example
+ *   import { startProfile } from '@adonis-agora/telescope/watchers'
+ *   const span = startProfile('checkout')
+ *   // ... work ...
+ *   span.mark('validated')
+ *   // ... more work ...
+ *   span.end()
+ */
+export function startProfile(label) {
+    const watcher = getDefaultProfilingWatcher();
+    return watcher ? watcher.startProfile(label) : NOOP_SESSION;
+}
+/**
+ * Time `fn` as a profiling span through the provider-published default watcher.
+ * A no-op passthrough (just runs `fn`) when the profiling watcher is not enabled.
+ *
+ * @example
+ *   import { profile } from '@adonis-agora/telescope/watchers'
+ *   const order = await profile('checkout', async (span) => {
+ *     const cart = await loadCart()
+ *     span.mark('cart-loaded')
+ *     return placeOrder(cart)
+ *   })
+ */
+export function profile(label, fn) {
+    const watcher = getDefaultProfilingWatcher();
+    if (watcher)
+        return watcher.profile(label, fn);
+    return fn(NOOP_SESSION);
+}
+//# sourceMappingURL=profiling_watcher.js.map

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

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

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

@@ -3,6 +3,11 @@
  * from `nestjs-telescope`'s query family-hash so a dashboard can roll up every
  * execution of `select * from users where id = ?` regardless of the id.
  */
-/** Grouping key for "the same query" — same template, any bound values. */
-export declare function queryFamilyHash(sql: string): string;
+/**
+ * Grouping key for "the same query". With `normalize` on (the default) the SQL is
+ * templated first, so every execution of the same shape shares a hash regardless
+ * of bound values; with it off the raw SQL is hashed verbatim (whitespace/literals
+ * distinguish entries — no cross-execution grouping).
+ */
+export declare function queryFamilyHash(sql: string, normalize?: boolean): string;
 //# sourceMappingURL=query_family_hash.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"query_family_hash.d.ts","sourceRoot":"","sources":["../../../src/watchers/query_family_hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyBH,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD"}
+{"version":3,"file":"query_family_hash.d.ts","sourceRoot":"","sources":["../../../src/watchers/query_family_hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAyBH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,UAAO,GAAG,MAAM,CAErE"}

package/dist/src/watchers/query_family_hash.js

@@ -24,8 +24,13 @@ function fnv1a(input) {
     }
     return (hash >>> 0).toString(16).padStart(8, '0');
 }
-/** Grouping key for "the same query" — same template, any bound values. */
-export function queryFamilyHash(sql) {
-    return fnv1a(normalizeSql(sql));
+/**
+ * Grouping key for "the same query". With `normalize` on (the default) the SQL is
+ * templated first, so every execution of the same shape shares a hash regardless
+ * of bound values; with it off the raw SQL is hashed verbatim (whitespace/literals
+ * distinguish entries — no cross-execution grouping).
+ */
+export function queryFamilyHash(sql, normalize = true) {
+    return fnv1a(normalize ? normalizeSql(sql) : sql);
 }
 //# sourceMappingURL=query_family_hash.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"query_family_hash.js","sourceRoot":"","sources":["../../../src/watchers/query_family_hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG;SACP,WAAW,EAAE;SACb,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,kBAAkB;SAClD,OAAO,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAC,mBAAmB;SACtD,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,8EAA8E;AAC9E,SAAS,KAAK,CAAC,KAAa;IAC1B,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"query_family_hash.js","sourceRoot":"","sources":["../../../src/watchers/query_family_hash.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG;SACP,WAAW,EAAE;SACb,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC,kBAAkB;SAClD,OAAO,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAC,mBAAmB;SACtD,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CAAC;AACZ,CAAC;AAED,8EAA8E;AAC9E,SAAS,KAAK,CAAC,KAAa;IAC1B,IAAI,IAAI,GAAG,UAAU,CAAC;IACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,SAAS,GAAG,IAAI;IAC3D,OAAO,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../src/watchers/record.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,cAAc,GAAG,IAAI,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAmBnE"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../src/watchers/record.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,cAAc,GAAG,IAAI,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAsBnE"}

package/dist/src/watchers/record.js

@@ -31,6 +31,10 @@ export function safeRecord(input, source) {
     }
     if (!store)
         return;
+    // Honour the overload guard's shed flag: while paused, drop new entries so a
+    // lagging event loop is never made worse by telescope's own write path.
+    if (getTelescopeRuntime().paused)
+        return;
     try {
         const resolved = input.traceId === undefined ? { ...input, traceId: currentTraceId() } : input;
         // Fire-and-forget: the store is async but the subscriber is sync. Swallow

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

@@ -1 +1 @@
-{"version":3,"file":"record.js","sourceRoot":"","sources":["../../../src/watchers/record.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,mBAAmB,EAAE,CAAC,KAAK,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAkB,EAAE,MAAc;IAC3D,IAAI,KAA4B,CAAC;IACjC,IAAI,CAAC;QACH,KAAK,GAAG,YAAY,EAAE,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO;IAEnB,IAAI,CAAC;QACH,MAAM,QAAQ,GACZ,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QAChF,0EAA0E;QAC1E,sEAAsE;QACtE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACxF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,MAAc,EAAE,GAAY;IAC/C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,uCAAuC,OAAO,EAAE,CAAC,CAAC;AAC3E,CAAC"}
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../../src/watchers/record.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,mBAAmB,EAAE,CAAC,KAAK,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAkB,EAAE,MAAc;IAC3D,IAAI,KAA4B,CAAC;IACjC,IAAI,CAAC;QACH,KAAK,GAAG,YAAY,EAAE,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO;IACnB,6EAA6E;IAC7E,wEAAwE;IACxE,IAAI,mBAAmB,EAAE,CAAC,MAAM;QAAE,OAAO;IAEzC,IAAI,CAAC;QACH,MAAM,QAAQ,GACZ,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QAChF,0EAA0E;QAC1E,sEAAsE;QACtE,KAAK,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IACxF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,MAAc,EAAE,GAAY;IAC/C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,uCAAuC,OAAO,EAAE,CAAC,CAAC;AAC3E,CAAC"}