@adonis-agora/telescope 0.4.0 → 0.5.1

package/dist/src/metrics/pulse.js

@@ -0,0 +1,414 @@
+import { EntryType } from '../entry.js';
+import { detectNPlusOne } from '../query/n_plus_one.js';
+import { percentile, summarizeStats, } from './stats.js';
+import { bucketTimeseries } from './timeseries.js';
+/**
+ * The Pulse feature — an aggregated "at a glance" health rollup over recorded
+ * telescope entries. Ported from `nestjs-telescope`'s `pulse.service` +
+ * `pulse-summary`, adapted to the Adonis entry model (a single-pass scan over
+ * entries that already carry their `content`, N+1 grouped by `traceId` rather
+ * than the NestJS `batchId`) and to REUSE the existing metrics primitives:
+ * {@link summarizeStats} (request status + cache hit ratio + exception groups),
+ * {@link bucketTimeseries} (throughput), {@link percentile} (slow-hotspot p99),
+ * and {@link detectNPlusOne} (N+1 loops). Pure aggregation lives in
+ * {@link summarizePulse}; {@link PulseService} adds the windowed store scan.
+ */
+const DEFAULT_WINDOW_MS = 3_600_000;
+const DEFAULT_TOP_N = 5;
+const DEFAULT_BUCKETS = 60;
+const MAX_BUCKETS = 500;
+/** Threshold (ms) at/above which a latency sample counts as "slow". */
+const DEFAULT_SLOW_MS = 100;
+/**
+ * Min p99 (ms) a route/outgoing family must reach to surface as a slow hotspot,
+ * so a quiet, healthy host's fastest-of-the-slow route (e.g. `/health` at 18ms)
+ * is not a false alarm. Matches the NestJS pulse default.
+ */
+const DEFAULT_SLOW_ROUTE_MS = 1000;
+/** Min repetitions of one query template within a trace to flag an N+1 loop. */
+const DEFAULT_NPLUSONE_THRESHOLD = 5;
+/** Min samples a family needs before it can rank as a hotspot. */
+const DEFAULT_HOTSPOT_MIN_COUNT = 1;
+/** Safety cap on entries scanned per pulse; surfaced via `truncated`. */
+const DEFAULT_SCAN_CAP = 50_000;
+const MAX_LABEL_LENGTH = 500;
+/** The togglable pulse cards. `counts` and the window meta are always present. */
+export const PULSE_CARDS = [
+    'throughput',
+    'requests',
+    'cache',
+    'slowest',
+    'slowRoutes',
+    'slowOutgoing',
+    'slowJobs',
+    'exceptions',
+    'nPlusOne',
+    'loadByUser',
+];
+function truncate(value) {
+    return value.length > MAX_LABEL_LENGTH ? `${value.slice(0, MAX_LABEL_LENGTH)}…` : value;
+}
+function asRecord(content) {
+    return typeof content === 'object' && content !== null
+        ? content
+        : null;
+}
+/** A human label for a slow entry, derived from its content by type. */
+function labelFrom(entry) {
+    const record = asRecord(entry.content);
+    if (record === null)
+        return entry.familyHash ?? entry.type;
+    if (typeof record.url === 'string') {
+        return typeof record.method === 'string' ? `${record.method} ${record.url}` : record.url;
+    }
+    if (typeof record.sql === 'string')
+        return record.sql;
+    if (typeof record.queue === 'string' && typeof record.name === 'string') {
+        return `${record.queue}:${record.name}`;
+    }
+    return entry.familyHash ?? entry.type;
+}
+/** The route family for a request entry: its `familyHash`, else `METHOD url`. */
+function routeKey(entry) {
+    if (entry.familyHash !== null)
+        return entry.familyHash;
+    const record = asRecord(entry.content);
+    if (record === null)
+        return null;
+    if (typeof record.url !== 'string')
+        return null;
+    return typeof record.method === 'string' ? `${record.method} ${record.url}` : record.url;
+}
+/** Extract the user id from a `user:<id>` tag, or `null` when none is present. */
+function userFromTags(tags) {
+    for (const tag of tags) {
+        if (tag.startsWith('user:'))
+            return tag.slice('user:'.length);
+    }
+    return null;
+}
+/** Rank per-family durations into hotspots by p99, gated by min-count (+ optional slow-ms). */
+function toHotspots(durationsByFamily, options, slowRouteMs) {
+    return [...durationsByFamily.entries()]
+        .map(([route, durations]) => {
+        const sorted = [...durations].sort((a, b) => a - b);
+        return {
+            route,
+            count: sorted.length,
+            p99: percentile(sorted, 0.99),
+            p50: percentile(sorted, 0.5),
+        };
+    })
+        .filter((h) => h.count >= options.hotspotMinCount && h.p99 >= slowRouteMs)
+        .sort((a, b) => b.p99 - a.p99 || b.count - a.count || a.route.localeCompare(b.route))
+        .slice(0, options.topN);
+}
+function pushDuration(map, key, durationMs) {
+    const existing = map.get(key);
+    if (existing)
+        existing.push(durationMs);
+    else
+        map.set(key, [durationMs]);
+}
+/** Empty request-health card (used when the `requests` card is disabled). */
+function emptyRequestHealth() {
+    return {
+        total: 0,
+        errorRate: 0,
+        status: { '2xx': 0, '3xx': 0, '4xx': 0, '5xx': 0, other: 0 },
+    };
+}
+/**
+ * Aggregate a window of entries — each carrying its `content` — into a
+ * {@link PulseSummary}. Pure: callers fetch the windowed entries and supply the
+ * window bounds. Reuses {@link summarizeStats}, {@link bucketTimeseries},
+ * {@link percentile}, and {@link detectNPlusOne} for the heavy lifting.
+ */
+export function summarizePulse(entries, windowStart, windowEnd, options, truncated = false) {
+    const enabled = (card) => options.cards.has(card);
+    const windowMs = Math.max(0, windowEnd.getTime() - windowStart.getTime());
+    const counts = {};
+    const slowCandidates = [];
+    const routeDurations = new Map();
+    const outgoingDurations = new Map();
+    const jobDurations = new Map();
+    const byTrace = new Map();
+    const userLoad = new Map();
+    const requestEntries = [];
+    const cacheEntries = [];
+    const exceptionEntries = [];
+    for (const entry of entries) {
+        counts[entry.type] = (counts[entry.type] ?? 0) + 1;
+        if (typeof entry.durationMs === 'number')
+            slowCandidates.push(entry);
+        if (entry.type === EntryType.Request) {
+            requestEntries.push(entry);
+            const route = routeKey(entry);
+            if (route !== null && typeof entry.durationMs === 'number') {
+                pushDuration(routeDurations, route, entry.durationMs);
+            }
+            const user = userFromTags(entry.tags);
+            if (user !== null) {
+                const duration = typeof entry.durationMs === 'number' ? entry.durationMs : 0;
+                const existing = userLoad.get(user);
+                if (existing) {
+                    existing.count += 1;
+                    existing.totalDurationMs += duration;
+                }
+                else {
+                    userLoad.set(user, { count: 1, totalDurationMs: duration });
+                }
+            }
+        }
+        else if (entry.type === EntryType.HttpClient) {
+            if (entry.familyHash !== null && typeof entry.durationMs === 'number') {
+                pushDuration(outgoingDurations, entry.familyHash, entry.durationMs);
+            }
+        }
+        else if (entry.type === EntryType.Job) {
+            if (entry.familyHash !== null && typeof entry.durationMs === 'number') {
+                pushDuration(jobDurations, entry.familyHash, entry.durationMs);
+            }
+        }
+        else if (entry.type === EntryType.Cache) {
+            cacheEntries.push(entry);
+        }
+        else if (entry.type === EntryType.Exception) {
+            exceptionEntries.push(entry);
+        }
+        if (entry.traceId !== null && entry.type === EntryType.Query) {
+            const bucket = byTrace.get(entry.traceId);
+            if (bucket)
+                bucket.push(entry);
+            else
+                byTrace.set(entry.traceId, [entry]);
+        }
+    }
+    // Throughput — reuse bucketTimeseries.
+    const overTime = bucketTimeseries(entries, windowStart, windowEnd, options.buckets);
+    const minutes = windowMs > 0 ? windowMs / 60_000 : 0;
+    const throughput = enabled('throughput')
+        ? {
+            total: entries.length,
+            perMinute: minutes > 0 ? entries.length / minutes : 0,
+            overTime,
+        }
+        : { total: 0, perMinute: 0, overTime };
+    // Request health — reuse summarizeStats for status + latency.
+    let requests = emptyRequestHealth();
+    if (enabled('requests')) {
+        const stats = summarizeStats({
+            entries: requestEntries,
+            type: EntryType.Request,
+            windowStart,
+            windowEnd,
+            windowMs,
+            buckets: options.buckets,
+            slowMs: options.slowMs,
+            truncated,
+        });
+        const status = stats.status ?? emptyRequestHealth().status;
+        const failed = status['4xx'] + status['5xx'];
+        requests = {
+            total: requestEntries.length,
+            errorRate: requestEntries.length > 0 ? failed / requestEntries.length : 0,
+            status,
+            ...(stats.latency !== undefined ? { latency: stats.latency } : {}),
+        };
+    }
+    // Cache hit ratio — reuse summarizeStats' cache aggregate.
+    let cache;
+    if (enabled('cache') && cacheEntries.length > 0) {
+        const stats = summarizeStats({
+            entries: cacheEntries,
+            type: EntryType.Cache,
+            windowStart,
+            windowEnd,
+            windowMs,
+            buckets: options.buckets,
+            slowMs: options.slowMs,
+            truncated,
+        });
+        cache = stats.cache;
+    }
+    // Top exceptions — reuse summarizeStats' exception grouping.
+    let topExceptions = [];
+    if (enabled('exceptions') && exceptionEntries.length > 0) {
+        const stats = summarizeStats({
+            entries: exceptionEntries,
+            type: EntryType.Exception,
+            windowStart,
+            windowEnd,
+            windowMs,
+            buckets: options.buckets,
+            slowMs: options.slowMs,
+            truncated,
+            topExceptions: options.topN,
+        });
+        topExceptions = (stats.exceptions ?? []).map((group) => ({
+            key: group.key,
+            class: group.class,
+            message: group.message,
+            count: group.count,
+            lastSeen: group.lastAt.toISOString(),
+        }));
+    }
+    // Slowest entries across all types.
+    const slowest = enabled('slowest')
+        ? slowCandidates
+            .slice()
+            .sort((a, b) => (b.durationMs ?? 0) - (a.durationMs ?? 0) || a.id.localeCompare(b.id))
+            .slice(0, options.topN)
+            .map((entry) => ({
+            id: entry.id,
+            type: entry.type,
+            durationMs: entry.durationMs,
+            label: truncate(labelFrom(entry)),
+            traceId: entry.traceId,
+        }))
+        : [];
+    // Slow hotspots — reuse percentile via toHotspots.
+    const slowRoutes = enabled('slowRoutes')
+        ? toHotspots(routeDurations, options, options.slowRouteMs)
+        : [];
+    const slowOutgoing = enabled('slowOutgoing')
+        ? toHotspots(outgoingDurations, options, options.slowRouteMs)
+        : [];
+    // Jobs are not gated by the slow-ms threshold — the slowest jobs always matter.
+    const slowJobs = enabled('slowJobs') ? toHotspots(jobDurations, options, 0) : [];
+    // N+1 hotspots — reuse detectNPlusOne per trace, aggregated across traces.
+    let nPlusOne = [];
+    if (enabled('nPlusOne')) {
+        const hotspots = new Map();
+        const familyDurationInTrace = new Map();
+        for (const [traceId, traceEntries] of byTrace) {
+            familyDurationInTrace.clear();
+            for (const entry of traceEntries) {
+                if (entry.familyHash !== null && typeof entry.durationMs === 'number') {
+                    familyDurationInTrace.set(entry.familyHash, (familyDurationInTrace.get(entry.familyHash) ?? 0) + entry.durationMs);
+                }
+            }
+            for (const insight of detectNPlusOne(traceEntries, options.nPlusOneThreshold)) {
+                const loopDuration = familyDurationInTrace.get(insight.familyHash) ?? 0;
+                const existing = hotspots.get(insight.familyHash);
+                if (existing) {
+                    existing.traces += 1;
+                    existing.total += insight.count;
+                    existing.totalDurationMs += loopDuration;
+                    if (insight.count > existing.perRequest) {
+                        existing.perRequest = insight.count;
+                        existing.sampleTraceId = traceId;
+                    }
+                }
+                else {
+                    hotspots.set(insight.familyHash, {
+                        familyHash: insight.familyHash,
+                        sql: insight.sql,
+                        perRequest: insight.count,
+                        traces: 1,
+                        total: insight.count,
+                        totalDurationMs: loopDuration,
+                        sampleTraceId: traceId,
+                    });
+                }
+            }
+        }
+        nPlusOne = [...hotspots.values()]
+            .sort((a, b) => b.totalDurationMs - a.totalDurationMs ||
+            b.total - a.total ||
+            b.traces - a.traces ||
+            a.familyHash.localeCompare(b.familyHash))
+            .slice(0, options.topN)
+            .map((h) => ({
+            familyHash: h.familyHash,
+            sql: truncate(h.sql),
+            perRequest: h.perRequest,
+            traces: h.traces,
+            total: h.total,
+            totalDurationMs: h.totalDurationMs,
+            sampleTraceId: h.sampleTraceId,
+        }));
+    }
+    // Load by user — top users by total request time.
+    const loadByUser = enabled('loadByUser')
+        ? [...userLoad.entries()]
+            .map(([user, load]) => ({ user, count: load.count, totalDurationMs: load.totalDurationMs }))
+            .sort((a, b) => b.totalDurationMs - a.totalDurationMs ||
+            b.count - a.count ||
+            a.user.localeCompare(b.user))
+            .slice(0, options.topN)
+        : [];
+    return {
+        windowStart: windowStart.toISOString(),
+        windowEnd: windowEnd.toISOString(),
+        windowMs,
+        counts,
+        throughput,
+        requests,
+        ...(cache !== undefined ? { cache } : {}),
+        slowest,
+        slowRoutes,
+        slowOutgoing,
+        slowJobs,
+        topExceptions,
+        nPlusOne,
+        loadByUser,
+        scanned: entries.length,
+        truncated,
+    };
+}
+/**
+ * Read-only Pulse rollup over a {@link TelescopeStore}. Storage-agnostic — it
+ * reads the store (the source of truth) on demand through the newest-first
+ * {@link TelescopeStore.list} contract, never a specific provider, and never a
+ * live counter. Analysis reads ALREADY-redacted stored entries, so redaction is
+ * never bypassed. Idiomatic Adonis: a plain class, no DI decorators (constructed
+ * by the provider / {@link TelescopeService}, exactly like {@link import('./metrics_service.js').MetricsService}).
+ */
+export class PulseService {
+    store;
+    windowMs;
+    scanCap;
+    base;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.windowMs = positiveOr(options.windowMs, DEFAULT_WINDOW_MS);
+        this.scanCap = positiveOr(options.scanCap, DEFAULT_SCAN_CAP);
+        this.base = {
+            topN: positiveOr(options.topN, DEFAULT_TOP_N),
+            buckets: clampBuckets(options.buckets),
+            slowMs: options.slowMs ?? DEFAULT_SLOW_MS,
+            slowRouteMs: options.slowRouteMs ?? DEFAULT_SLOW_ROUTE_MS,
+            hotspotMinCount: options.hotspotMinCount ?? DEFAULT_HOTSPOT_MIN_COUNT,
+            nPlusOneThreshold: positiveOr(options.nPlusOneThreshold, DEFAULT_NPLUSONE_THRESHOLD),
+            cards: options.cards ? new Set(options.cards) : new Set(PULSE_CARDS),
+        };
+    }
+    /**
+     * Build the health snapshot over the trailing window. `query.windowMs` /
+     * `query.topN` override the configured defaults for a single call.
+     */
+    async getHealth(query = {}) {
+        const windowMs = query.windowMs ?? this.windowMs;
+        if (!Number.isFinite(windowMs) || windowMs <= 0) {
+            throw new RangeError(`windowMs must be a positive, finite number (got ${windowMs}).`);
+        }
+        const windowEnd = new Date();
+        const windowStart = new Date(windowEnd.getTime() - windowMs);
+        const listQuery = { after: windowStart, limit: this.scanCap };
+        const entries = await this.store.list(listQuery);
+        const truncated = entries.length >= this.scanCap;
+        const options = {
+            ...this.base,
+            topN: query.topN ?? this.base.topN,
+        };
+        return summarizePulse(entries, windowStart, windowEnd, options, truncated);
+    }
+}
+function positiveOr(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function clampBuckets(buckets) {
+    return Math.min(MAX_BUCKETS, Math.max(1, Math.floor(buckets ?? DEFAULT_BUCKETS)));
+}
+//# sourceMappingURL=pulse.js.map

package/dist/src/metrics/pulse.js.map

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

package/dist/src/overload_guard.d.ts

@@ -0,0 +1,77 @@
+import type { ResolvedTelescopeConfig } from './define_config.js';
+/** The resolved overload-guard slice of the telescope config. */
+export type ResolvedOverloadConfig = ResolvedTelescopeConfig['overload'];
+/**
+ * The pause surface the guard toggles: the ingestion path is expected to become a
+ * dropping no-op while `isPaused` is `true`. The provider backs this with the
+ * global runtime `paused` flag the request middleware and watcher `safeRecord`
+ * honour, so a pause sheds ingestion across every recording entry point at once.
+ */
+export interface PauseController {
+    pause(): void;
+    resume(): void;
+    readonly isPaused: boolean;
+}
+/** The minimal `perf_hooks` monitor surface the guard reads — injectable for tests. */
+export interface EventLoopDelayMonitor {
+    enable(): void;
+    disable(): void;
+    reset(): void;
+    /** Delay at the given percentile, in nanoseconds. */
+    percentile(percentile: number): number;
+}
+/** The sink for the guard's operational messages. Defaults to `console`. */
+export interface OverloadLogger {
+    warn(message: string): void;
+    log?(message: string): void;
+}
+/** Constructor seams for {@link OverloadGuard} (monitor factory + logger). */
+export interface OverloadGuardDeps {
+    /** Build the event-loop-delay monitor. Defaults to `perf_hooks`; `null` ⇒ no-op. */
+    monitorFactory?: () => EventLoopDelayMonitor | null;
+    logger?: OverloadLogger;
+}
+/**
+ * Overload protection. Samples the process event-loop delay histogram
+ * (`perf_hooks.monitorEventLoopDelay`) on an interval and PAUSES ingestion via the
+ * {@link PauseController} when the p99 lag crosses the configured threshold,
+ * resuming once it recovers — so a telescope under load can never amplify an
+ * incident.
+ *
+ * A startup grace (default ~5s) discards the first measurement windows so the
+ * synchronous boot stall (provider wiring, migrations) never trips the guard on a
+ * transient. Degrades to a no-op when `perf_hooks.monitorEventLoopDelay` is
+ * unavailable or `overload.enabled` is `false`. The sampling interval is unref'd so
+ * it never keeps the host's event loop alive.
+ *
+ * Ported from `nestjs-telescope`'s `TelescopeOverloadGuard`; the only adaptation is
+ * that it pauses a {@link PauseController} (the runtime flag) rather than a NestJS
+ * Recorder, matching this package's DI-free ingestion path.
+ */
+export declare class OverloadGuard {
+    private readonly controller;
+    private readonly maxLagMs;
+    /**
+     * Number of leading sample windows still to discard for the startup grace.
+     * Counts down on every sample taken while warming up, after which the guard
+     * judges normally.
+     */
+    private warmupSamplesRemaining;
+    private monitor;
+    private timer;
+    private readonly monitorFactory;
+    private readonly logger;
+    constructor(config: ResolvedOverloadConfig, controller: PauseController, deps?: OverloadGuardDeps);
+    /**
+     * Arm the guard: start the monitor + sampling timer. A no-op when protection is
+     * off, already started, or `perf_hooks` lacks the monitor.
+     */
+    start(): void;
+    /** Stop sampling and disable the monitor (called by the provider at shutdown). */
+    stop(): void;
+    /** Run exactly one sampling tick. Exposed so tests can drive the guard deterministically. */
+    sampleOnce(): void;
+    /** Read the rolling p99 lag and pause/resume ingestion around the threshold. */
+    private sample;
+}
+//# sourceMappingURL=overload_guard.d.ts.map

package/dist/src/overload_guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overload_guard.d.ts","sourceRoot":"","sources":["../../src/overload_guard.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAMlE,iEAAiE;AACjE,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,IAAI,IAAI,CAAC;IACd,MAAM,IAAI,IAAI,CAAC;IACf,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,uFAAuF;AACvF,MAAM,WAAW,qBAAqB;IACpC,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,IAAI,CAAC;IAChB,KAAK,IAAI,IAAI,CAAC;IACd,qDAAqD;IACrD,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CACxC;AAED,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,qBAAqB,GAAG,IAAI,CAAC;IACpD,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IAetB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAd7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC;;;;OAIG;IACH,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqC;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAGtC,MAAM,EAAE,sBAAsB,EACb,UAAU,EAAE,eAAe,EAC5C,IAAI,GAAE,iBAAsB;IAU9B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAQb,kFAAkF;IAClF,IAAI,IAAI,IAAI;IASZ,6FAA6F;IAC7F,UAAU,IAAI,IAAI;IAIlB,gFAAgF;IAChF,OAAO,CAAC,MAAM;CAmCf"}

package/dist/src/overload_guard.js

@@ -0,0 +1,134 @@
+import * as perfHooks from 'node:perf_hooks';
+/** How often the guard samples the lag histogram. */
+const SAMPLE_INTERVAL_MS = 1_000;
+const NS_PER_MS = 1e6;
+/**
+ * Overload protection. Samples the process event-loop delay histogram
+ * (`perf_hooks.monitorEventLoopDelay`) on an interval and PAUSES ingestion via the
+ * {@link PauseController} when the p99 lag crosses the configured threshold,
+ * resuming once it recovers — so a telescope under load can never amplify an
+ * incident.
+ *
+ * A startup grace (default ~5s) discards the first measurement windows so the
+ * synchronous boot stall (provider wiring, migrations) never trips the guard on a
+ * transient. Degrades to a no-op when `perf_hooks.monitorEventLoopDelay` is
+ * unavailable or `overload.enabled` is `false`. The sampling interval is unref'd so
+ * it never keeps the host's event loop alive.
+ *
+ * Ported from `nestjs-telescope`'s `TelescopeOverloadGuard`; the only adaptation is
+ * that it pauses a {@link PauseController} (the runtime flag) rather than a NestJS
+ * Recorder, matching this package's DI-free ingestion path.
+ */
+export class OverloadGuard {
+    controller;
+    maxLagMs;
+    /**
+     * Number of leading sample windows still to discard for the startup grace.
+     * Counts down on every sample taken while warming up, after which the guard
+     * judges normally.
+     */
+    warmupSamplesRemaining;
+    monitor = null;
+    timer = null;
+    monitorFactory;
+    logger;
+    constructor(config, controller, deps = {}) {
+        this.controller = controller;
+        this.maxLagMs = config.enabled ? config.maxEventLoopLagMs : null;
+        // Round UP so a sub-interval grace still discards at least one window (the one
+        // that holds the bootstrap stall). 0ms ⇒ 0 windows ⇒ no grace.
+        this.warmupSamplesRemaining = Math.ceil(config.startupGraceMs / SAMPLE_INTERVAL_MS);
+        this.monitorFactory = deps.monitorFactory ?? startMonitor;
+        this.logger = deps.logger ?? console;
+    }
+    /**
+     * Arm the guard: start the monitor + sampling timer. A no-op when protection is
+     * off, already started, or `perf_hooks` lacks the monitor.
+     */
+    start() {
+        if (this.maxLagMs === null || this.timer)
+            return;
+        this.monitor = this.monitorFactory();
+        if (this.monitor === null)
+            return;
+        this.timer = setInterval(() => this.sample(), SAMPLE_INTERVAL_MS);
+        this.timer.unref?.();
+    }
+    /** Stop sampling and disable the monitor (called by the provider at shutdown). */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.monitor?.disable();
+        this.monitor = null;
+    }
+    /** Run exactly one sampling tick. Exposed so tests can drive the guard deterministically. */
+    sampleOnce() {
+        this.sample();
+    }
+    /** Read the rolling p99 lag and pause/resume ingestion around the threshold. */
+    sample() {
+        const monitor = this.monitor;
+        const maxLagMs = this.maxLagMs;
+        if (monitor === null || maxLagMs === null)
+            return;
+        let p99Ms;
+        try {
+            p99Ms = monitor.percentile(99) / NS_PER_MS;
+        }
+        catch {
+            return; // A misbehaving monitor must never crash the host.
+        }
+        // Reset the histogram each cycle so the decision reflects the RECENT window (a
+        // per-process accumulation would never recover once lag spiked).
+        monitor.reset();
+        // Startup grace: discard the leading window(s) — they carry the boot stall, not
+        // live load. Reset above still ran, so the NEXT judged window starts clean.
+        if (this.warmupSamplesRemaining > 0) {
+            this.warmupSamplesRemaining -= 1;
+            return;
+        }
+        if (p99Ms >= maxLagMs) {
+            if (!this.controller.isPaused) {
+                this.logger.warn(`Event-loop p99 lag ${p99Ms.toFixed(0)}ms >= ${maxLagMs}ms — pausing Telescope capture.`);
+                this.controller.pause();
+            }
+        }
+        else if (this.controller.isPaused) {
+            const info = this.logger.log ?? this.logger.warn;
+            info.call(this.logger, `Event-loop p99 lag ${p99Ms.toFixed(0)}ms recovered — resuming Telescope capture.`);
+            this.controller.resume();
+        }
+    }
+}
+/** Start an enabled event-loop-delay monitor, or `null` if perf_hooks lacks it. */
+function startMonitor() {
+    const factory = perfHooks.monitorEventLoopDelay;
+    if (typeof factory !== 'function')
+        return null;
+    try {
+        const monitor = factory();
+        if (!isEventLoopDelayMonitor(monitor))
+            return null;
+        monitor.enable();
+        return monitor;
+    }
+    catch {
+        return null;
+    }
+}
+/** Structural guard: confirms a value exposes the monitor surface we read. */
+function isEventLoopDelayMonitor(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('enable' in value) || !('disable' in value))
+        return false;
+    if (!('reset' in value) || !('percentile' in value))
+        return false;
+    return (typeof value.enable === 'function' &&
+        typeof value.disable === 'function' &&
+        typeof value.reset === 'function' &&
+        typeof value.percentile === 'function');
+}
+//# sourceMappingURL=overload_guard.js.map

package/dist/src/overload_guard.js.map

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