@adonis-agora/telescope 0.1.0 → 0.3.0

package/dist/src/index.js

@@ -17,11 +17,27 @@ export { defineTelescopeExtension } from './extension/types.js';
 export { ExtensionRegistry } from './extension/registry.js';
 // — config —
 export { defineConfig, resolveConfig } from './define_config.js';
+// — live-stream (SSE entry-events pub/sub) —
+export { EntryEvents } from './stream/entry_events.js';
+export { StreamingTelescopeStore } from './stream/streaming_store.js';
+export { DEFAULT_HEARTBEAT_MS, streamEntries } from './stream/stream_handler.js';
+// — sampling (tail-sampling on the write path) —
+export { isErrorEntry, passesSampling, resolveSampling, samplingRates, } from './sampling/sampling.js';
+export { SamplingTelescopeStore } from './sampling/sampling_store.js';
+// — query analysis (N+1 detection) —
+export { detectNPlusOne, detectNPlusOnePatterns } from './query/n_plus_one.js';
+// — metrics (stats / timeseries / percentiles / traces / waterfall) —
+export { MetricsService } from './metrics/metrics_service.js';
+export { estimateLatencyPercentiles, percentile, summarizeStats, } from './metrics/stats.js';
+export { bucketTimeseries } from './metrics/timeseries.js';
+export { summarizeTraces } from './metrics/traces.js';
+export { buildWaterfall } from './metrics/waterfall.js';
+export { buildHistogram, emptyHistogram, estimatePercentileFromHistogram, HISTOGRAM_BUCKET_COUNT, histogramBucketIndex, incrementHistogram, LATENCY_BOUNDARIES_MS, mergeHistograms, normalizeHistogram, ROLLUP_BUCKET_MS, } from './metrics/rollup.js';
 // — redaction —
 export { compileRedactSpec, DEFAULT_MASK, DEFAULT_REDACT_KEYS, redact, redactBounded, redactBoundedWith, } from './redaction/redact.js';
 export { RedactingTelescopeStore } from './redaction/redacting_store.js';
 // — runtime (advanced) —
-export { getTelescopeRuntime, resetTelescopeRuntime, setTelescopeExtensionRegistry, setTelescopeRuntime, } from './registry.js';
+export { getTelescopeRuntime, resetTelescopeRuntime, setTelescopeEntryEvents, setTelescopeExtensionRegistry, setTelescopeRuntime, } from './registry.js';
 // — structural ecosystem readers —
 export { currentTraceId, getContextAccessor } from './context_accessor.js';
 export { getDiagnosticsRegistry, isDiagnosticEvent, } from './diagnostics_registry.js';

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,kBAAkB;AAClB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAS3B,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAQ9C,gBAAgB;AAChB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,eAAe;AACf,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAMrD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAKhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGjE,oBAAoB;AACpB,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAehE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,aAAa;AACb,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAQjE,gBAAgB;AAChB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,MAAM,EACN,aAAa,EACb,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAEzE,yBAAyB;AACzB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,6BAA6B,EAC7B,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,mCAAmC;AACnC,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3E,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,kBAAkB;AAClB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAS3B,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAQ9C,gBAAgB;AAChB,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGhD,eAAe;AACf,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAMrD,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAKhC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGjE,oBAAoB;AACpB,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAehE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,aAAa;AACb,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUjE,6CAA6C;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAEvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAGjF,iDAAiD;AACjD,OAAO,EACL,YAAY,EACZ,cAAc,EACd,eAAe,EACf,aAAa,GACd,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE,qCAAqC;AACrC,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAO/E,sEAAsE;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAM9D,OAAO,EACL,0BAA0B,EAC1B,UAAU,EACV,cAAc,GACf,MAAM,oBAAoB,CAAC;AAW5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,EACL,cAAc,EACd,cAAc,EACd,+BAA+B,EAC/B,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,gBAAgB;AAChB,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,MAAM,EACN,aAAa,EACb,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAEzE,yBAAyB;AACzB,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,EAC7B,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,mCAAmC;AACnC,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3E,OAAO,EACL,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,2BAA2B,CAAC"}

package/dist/src/metrics/metrics_service.d.ts

@@ -0,0 +1,63 @@
+import { type NPlusOneInsight, type NPlusOnePattern } from '../query/n_plus_one.js';
+import type { TelescopeStore } from '../store.js';
+import { type StatsResult } from './stats.js';
+import { type TimeseriesReport } from './timeseries.js';
+import { type TraceSummary } from './traces.js';
+import { type Waterfall } from './waterfall.js';
+export interface StatsQuery {
+    /** Required — stats are computed per entry type. */
+    type: string;
+    windowMs: number;
+    buckets?: number;
+}
+export interface TimeseriesQuery {
+    windowMs: number;
+    buckets?: number;
+    /** Optionally scope the series to a single entry type. */
+    type?: string;
+}
+export interface MetricsServiceOptions {
+    /** Threshold (ms) at/above which an entry counts as slow. Default 100. */
+    slowMs?: number;
+    defaultBuckets?: number;
+    scanCap?: number;
+    /** Minimum repetitions to flag an N+1 loop. Default 3. */
+    nPlusOneThreshold?: number;
+}
+/**
+ * Read-only analytics over the {@link TelescopeStore}: per-type stats (latency
+ * percentiles, family/cache/status/exception breakdowns), throughput timeseries,
+ * a trace list, a per-trace span waterfall, and N+1 query detection.
+ *
+ * Storage-agnostic — it works through the {@link TelescopeStore.list} interface
+ * only (newest-first), never a specific provider. Analysis reads ALREADY-redacted
+ * stored entries, so redaction is never bypassed.
+ */
+export declare class MetricsService {
+    private readonly store;
+    private readonly slowMs;
+    private readonly defaultBuckets;
+    private readonly scanCap;
+    private readonly nPlusOneThreshold;
+    constructor(store: TelescopeStore, options?: MetricsServiceOptions);
+    /** Per-type analytics over a trailing window. */
+    getStats(query: StatsQuery): Promise<StatsResult>;
+    /** Throughput time-series over a trailing window (total + per-type per bucket). */
+    getTimeseries(query: TimeseriesQuery): Promise<TimeseriesReport>;
+    /** Recent traces, newest-last-seen first. */
+    getTraces(limit?: number): Promise<TraceSummary[]>;
+    /** The span waterfall for a single trace, or `null` when the trace is empty. */
+    getWaterfall(traceId: string): Promise<Waterfall | null>;
+    /**
+     * N+1 query patterns within a single trace (loop attribution + wasted-time
+     * ranking). The store returns newest-first; the detector needs oldest-first
+     * record order to attribute the driving parent, so we reverse.
+     */
+    getNPlusOne(traceId: string, threshold?: number): Promise<NPlusOnePattern[]>;
+    /** Flat family-count N+1 insights within a single trace. */
+    getNPlusOneFlat(traceId: string, threshold?: number): Promise<NPlusOneInsight[]>;
+    private clampBuckets;
+    /** Fetch entries matching `query` (newest-first), capped at `scanCap`. */
+    private collect;
+}
+//# sourceMappingURL=metrics_service.d.ts.map

package/dist/src/metrics/metrics_service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics_service.d.ts","sourceRoot":"","sources":["../../../src/metrics/metrics_service.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,eAAe,EAGrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAc,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,KAAK,WAAW,EAA8C,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,KAAK,gBAAgB,EAAoB,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,KAAK,YAAY,EAAmB,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,SAAS,EAAkB,MAAM,gBAAgB,CAAC;AAShE,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAc;IAOvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;gBAGxB,KAAK,EAAE,cAAc,EACtC,OAAO,GAAE,qBAA0B;IAQrC,iDAAiD;IAC3C,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAkCvD,mFAAmF;IAC7E,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IActE,6CAA6C;IACvC,SAAS,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAKpD,gFAAgF;IAC1E,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAK9D;;;;OAIG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAQlF,4DAA4D;IACtD,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAMtF,OAAO,CAAC,YAAY;IAIpB,0EAA0E;YAC5D,OAAO;CAItB"}

package/dist/src/metrics/metrics_service.js

@@ -0,0 +1,116 @@
+import { detectNPlusOne, detectNPlusOnePatterns, } from '../query/n_plus_one.js';
+import { estimateLatencyPercentiles, summarizeStats } from './stats.js';
+import { bucketTimeseries } from './timeseries.js';
+import { summarizeTraces } from './traces.js';
+import { buildWaterfall } from './waterfall.js';
+const DEFAULT_BUCKETS = 60;
+const MAX_BUCKETS = 500;
+const DEFAULT_SLOW_MS = 100;
+/** Safety cap on entries scanned per analytics request; surfaced via `truncated`. */
+const DEFAULT_SCAN_CAP = 50_000;
+const DEFAULT_NPLUSONE_THRESHOLD = 3;
+/**
+ * Read-only analytics over the {@link TelescopeStore}: per-type stats (latency
+ * percentiles, family/cache/status/exception breakdowns), throughput timeseries,
+ * a trace list, a per-trace span waterfall, and N+1 query detection.
+ *
+ * Storage-agnostic — it works through the {@link TelescopeStore.list} interface
+ * only (newest-first), never a specific provider. Analysis reads ALREADY-redacted
+ * stored entries, so redaction is never bypassed.
+ */
+export class MetricsService {
+    store;
+    slowMs;
+    defaultBuckets;
+    scanCap;
+    nPlusOneThreshold;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.slowMs = options.slowMs ?? DEFAULT_SLOW_MS;
+        this.defaultBuckets = options.defaultBuckets ?? DEFAULT_BUCKETS;
+        this.scanCap = options.scanCap ?? DEFAULT_SCAN_CAP;
+        this.nPlusOneThreshold = options.nPlusOneThreshold ?? DEFAULT_NPLUSONE_THRESHOLD;
+    }
+    /** Per-type analytics over a trailing window. */
+    async getStats(query) {
+        if (!Number.isFinite(query.windowMs) || query.windowMs <= 0) {
+            throw new RangeError(`windowMs must be a positive, finite number (got ${query.windowMs}).`);
+        }
+        const buckets = this.clampBuckets(query.buckets);
+        const windowEnd = new Date();
+        const windowStart = new Date(windowEnd.getTime() - query.windowMs);
+        const { entries, truncated } = await this.collect({
+            type: query.type,
+            after: windowStart,
+        });
+        // Histogram-based percentile estimate over the windowed durations — the
+        // storage-agnostic stand-in for the NestJS rollup fast path. count/max/slow
+        // stay raw-derived inside summarizeStats.
+        const durations = entries
+            .map((entry) => entry.durationMs)
+            .filter((d) => typeof d === 'number');
+        const latencyPercentiles = estimateLatencyPercentiles(durations);
+        return summarizeStats({
+            entries,
+            type: query.type,
+            windowStart,
+            windowEnd,
+            windowMs: query.windowMs,
+            buckets,
+            slowMs: this.slowMs,
+            truncated,
+            ...(latencyPercentiles !== undefined ? { latencyPercentiles } : {}),
+        });
+    }
+    /** Throughput time-series over a trailing window (total + per-type per bucket). */
+    async getTimeseries(query) {
+        if (!Number.isFinite(query.windowMs) || query.windowMs <= 0) {
+            throw new RangeError(`windowMs must be a positive, finite number (got ${query.windowMs}).`);
+        }
+        const buckets = this.clampBuckets(query.buckets);
+        const windowEnd = new Date();
+        const windowStart = new Date(windowEnd.getTime() - query.windowMs);
+        const { entries } = await this.collect({
+            after: windowStart,
+            ...(query.type !== undefined ? { type: query.type } : {}),
+        });
+        return bucketTimeseries(entries, windowStart, windowEnd, buckets);
+    }
+    /** Recent traces, newest-last-seen first. */
+    async getTraces(limit = 50) {
+        const { entries } = await this.collect({});
+        return summarizeTraces(entries, { limit });
+    }
+    /** The span waterfall for a single trace, or `null` when the trace is empty. */
+    async getWaterfall(traceId) {
+        const entries = await this.store.list({ traceId });
+        return buildWaterfall(entries);
+    }
+    /**
+     * N+1 query patterns within a single trace (loop attribution + wasted-time
+     * ranking). The store returns newest-first; the detector needs oldest-first
+     * record order to attribute the driving parent, so we reverse.
+     */
+    async getNPlusOne(traceId, threshold) {
+        const entries = await this.store.list({ traceId });
+        const ordered = [...entries].reverse();
+        return detectNPlusOnePatterns(ordered, {
+            threshold: threshold ?? this.nPlusOneThreshold,
+        });
+    }
+    /** Flat family-count N+1 insights within a single trace. */
+    async getNPlusOneFlat(traceId, threshold) {
+        const entries = await this.store.list({ traceId });
+        const ordered = [...entries].reverse();
+        return detectNPlusOne(ordered, threshold ?? this.nPlusOneThreshold);
+    }
+    clampBuckets(buckets) {
+        return Math.min(MAX_BUCKETS, Math.max(1, Math.floor(buckets ?? this.defaultBuckets)));
+    }
+    /** Fetch entries matching `query` (newest-first), capped at `scanCap`. */
+    async collect(query) {
+        const entries = await this.store.list({ ...query, limit: this.scanCap });
+        return { entries, truncated: entries.length >= this.scanCap };
+    }
+}
+//# sourceMappingURL=metrics_service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics_service.js","sourceRoot":"","sources":["../../../src/metrics/metrics_service.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,cAAc,EACd,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAoB,0BAA0B,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAyB,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAqB,eAAe,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAkB,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhE,MAAM,eAAe,GAAG,EAAE,CAAC;AAC3B,MAAM,WAAW,GAAG,GAAG,CAAC;AACxB,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,qFAAqF;AACrF,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAChC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAyBrC;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAc;IAON;IANF,MAAM,CAAS;IACf,cAAc,CAAS;IACvB,OAAO,CAAS;IAChB,iBAAiB,CAAS;IAE3C,YACmB,KAAqB,EACtC,UAAiC,EAAE;QADlB,UAAK,GAAL,KAAK,CAAgB;QAGtC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,eAAe,CAAC;QAChD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,eAAe,CAAC;QAChE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;QACnD,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,IAAI,0BAA0B,CAAC;IACnF,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,QAAQ,CAAC,KAAiB;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,UAAU,CAAC,mDAAmD,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;QAEnE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC;YAChD,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,KAAK,EAAE,WAAW;SACnB,CAAC,CAAC;QAEH,wEAAwE;QACxE,4EAA4E;QAC5E,0CAA0C;QAC1C,MAAM,SAAS,GAAG,OAAO;aACtB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC;aAChC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;QACrD,MAAM,kBAAkB,GAAG,0BAA0B,CAAC,SAAS,CAAC,CAAC;QAEjE,OAAO,cAAc,CAAC;YACpB,OAAO;YACP,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,WAAW;YACX,SAAS;YACT,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,OAAO;YACP,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,SAAS;YACT,GAAG,CAAC,kBAAkB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpE,CAAC,CAAC;IACL,CAAC;IAED,mFAAmF;IACnF,KAAK,CAAC,aAAa,CAAC,KAAsB;QACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,UAAU,CAAC,mDAAmD,KAAK,CAAC,QAAQ,IAAI,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAC7B,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;QACnE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC;YACrC,KAAK,EAAE,WAAW;YAClB,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1D,CAAC,CAAC;QACH,OAAO,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACpE,CAAC;IAED,6CAA6C;IAC7C,KAAK,CAAC,SAAS,CAAC,KAAK,GAAG,EAAE;QACxB,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3C,OAAO,eAAe,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,YAAY,CAAC,OAAe;QAChC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACnD,OAAO,cAAc,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,OAAe,EAAE,SAAkB;QACnD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;QACvC,OAAO,sBAAsB,CAAC,OAAO,EAAE;YACrC,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,iBAAiB;SAC/C,CAAC,CAAC;IACL,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,eAAe,CAAC,OAAe,EAAE,SAAkB;QACvD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;QACvC,OAAO,cAAc,CAAC,OAAO,EAAE,SAAS,IAAI,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACtE,CAAC;IAEO,YAAY,CAAC,OAA2B;QAC9C,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,0EAA0E;IAClE,KAAK,CAAC,OAAO,CAAC,KAAiB;QACrC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;IAChE,CAAC;CACF"}

package/dist/src/metrics/rollup.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pre-aggregated latency histogram + percentile estimation. Ported faithfully
+ * from `nestjs-telescope`'s `rollup/rollup-store.ts` (the boundaries + histogram
+ * helpers) and `rollup/estimate-percentile.ts` (the bucket-resolution percentile).
+ *
+ * This is the storage-agnostic maths only — there is no rollup STORE in the
+ * Adonis port (the headless store has no rollup SPI). It exists so the metrics
+ * module can offer a histogram-based percentile path whose estimate agrees with
+ * the raw-scan nearest-rank percentile within one bucket-width (see the
+ * equivalence spec), exactly mirroring the NestJS invariants.
+ */
+/** One minute is the base rollup granularity. */
+export declare const ROLLUP_BUCKET_MS = 60000;
+/**
+ * Upper boundaries (inclusive, in ms) for the pre-aggregated latency histogram.
+ * Bucket `i` counts durations `d` where `d <= LATENCY_BOUNDARIES_MS[i]` and
+ * `d > LATENCY_BOUNDARIES_MS[i-1]`. A final OVERFLOW bucket counts everything
+ * greater than the last boundary, so a histogram always has
+ * `LATENCY_BOUNDARIES_MS.length + 1` cells.
+ */
+export declare const LATENCY_BOUNDARIES_MS: readonly number[];
+/** The fixed cell count of every latency histogram (boundaries + 1 overflow). */
+export declare const HISTOGRAM_BUCKET_COUNT: number;
+/** A fresh, all-zeros histogram of the canonical fixed length. */
+export declare function emptyHistogram(): number[];
+/**
+ * The histogram cell a duration falls in: the first index `i` where
+ * `durationMs <= LATENCY_BOUNDARIES_MS[i]`, else the overflow index. Negative or
+ * zero durations land in cell 0.
+ */
+export declare function histogramBucketIndex(durationMs: number): number;
+/** Increments the histogram cell for `durationMs` by one, in place. */
+export declare function incrementHistogram(histogram: number[], durationMs: number): void;
+/**
+ * Normalizes a (possibly legacy/undefined) histogram into a fixed-length
+ * zero-padded array — never NaN, never a wrong width.
+ */
+export declare function normalizeHistogram(histogram: number[] | null | undefined): number[];
+/**
+ * Element-wise additive merge of `addend` into a fresh histogram. Both are
+ * normalized first, so legacy/short arrays are safe.
+ */
+export declare function mergeHistograms(target: number[], addend: number[] | null | undefined): number[];
+/** Build a latency histogram from raw durations (ms). */
+export declare function buildHistogram(durations: Iterable<number>): number[];
+/**
+ * Estimates a percentile from a pre-aggregated latency histogram (O(buckets), no
+ * raw scan). Nearest-rank style at BUCKET resolution: the result is the UPPER
+ * boundary of the bucket that contains the target rank, so the estimate is an
+ * APPROXIMATION whose error is bounded by that bucket's width.
+ *
+ * - `total = Σ histogram`; `target rank = ceil(fraction * total)` (1-based,
+ *   matching the raw nearest-rank `Math.ceil(fraction * n)`).
+ * - Walk the cumulative count until it reaches/crosses the target rank; return
+ *   the containing bucket's upper boundary.
+ * - The OVERFLOW bucket has no finite upper boundary; we return the LAST boundary
+ *   as a safe finite representative (documented under-estimate, never `Infinity`).
+ * - Returns 0 when the histogram is empty / total is 0.
+ */
+export declare function estimatePercentileFromHistogram(histogram: number[], fraction: number): number;
+//# sourceMappingURL=rollup.d.ts.map

package/dist/src/metrics/rollup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollup.d.ts","sourceRoot":"","sources":["../../../src/metrics/rollup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAElD,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,QAAmC,CAAC;AAEvE,kEAAkE;AAClE,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAGhF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAQnF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CAO/F;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAIpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAmB7F"}

package/dist/src/metrics/rollup.js

@@ -0,0 +1,114 @@
+/**
+ * Pre-aggregated latency histogram + percentile estimation. Ported faithfully
+ * from `nestjs-telescope`'s `rollup/rollup-store.ts` (the boundaries + histogram
+ * helpers) and `rollup/estimate-percentile.ts` (the bucket-resolution percentile).
+ *
+ * This is the storage-agnostic maths only — there is no rollup STORE in the
+ * Adonis port (the headless store has no rollup SPI). It exists so the metrics
+ * module can offer a histogram-based percentile path whose estimate agrees with
+ * the raw-scan nearest-rank percentile within one bucket-width (see the
+ * equivalence spec), exactly mirroring the NestJS invariants.
+ */
+/** One minute is the base rollup granularity. */
+export const ROLLUP_BUCKET_MS = 60_000;
+/**
+ * Upper boundaries (inclusive, in ms) for the pre-aggregated latency histogram.
+ * Bucket `i` counts durations `d` where `d <= LATENCY_BOUNDARIES_MS[i]` and
+ * `d > LATENCY_BOUNDARIES_MS[i-1]`. A final OVERFLOW bucket counts everything
+ * greater than the last boundary, so a histogram always has
+ * `LATENCY_BOUNDARIES_MS.length + 1` cells.
+ */
+export const LATENCY_BOUNDARIES_MS = [
+    1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000,
+];
+/** The fixed cell count of every latency histogram (boundaries + 1 overflow). */
+export const HISTOGRAM_BUCKET_COUNT = LATENCY_BOUNDARIES_MS.length + 1;
+/** A fresh, all-zeros histogram of the canonical fixed length. */
+export function emptyHistogram() {
+    return new Array(HISTOGRAM_BUCKET_COUNT).fill(0);
+}
+/**
+ * The histogram cell a duration falls in: the first index `i` where
+ * `durationMs <= LATENCY_BOUNDARIES_MS[i]`, else the overflow index. Negative or
+ * zero durations land in cell 0.
+ */
+export function histogramBucketIndex(durationMs) {
+    for (let index = 0; index < LATENCY_BOUNDARIES_MS.length; index += 1) {
+        const boundary = LATENCY_BOUNDARIES_MS[index];
+        if (boundary !== undefined && durationMs <= boundary)
+            return index;
+    }
+    return LATENCY_BOUNDARIES_MS.length;
+}
+/** Increments the histogram cell for `durationMs` by one, in place. */
+export function incrementHistogram(histogram, durationMs) {
+    const index = histogramBucketIndex(durationMs);
+    histogram[index] = (histogram[index] ?? 0) + 1;
+}
+/**
+ * Normalizes a (possibly legacy/undefined) histogram into a fixed-length
+ * zero-padded array — never NaN, never a wrong width.
+ */
+export function normalizeHistogram(histogram) {
+    const normalized = emptyHistogram();
+    if (!Array.isArray(histogram))
+        return normalized;
+    for (let index = 0; index < HISTOGRAM_BUCKET_COUNT; index += 1) {
+        const value = histogram[index];
+        normalized[index] = typeof value === 'number' && Number.isFinite(value) ? value : 0;
+    }
+    return normalized;
+}
+/**
+ * Element-wise additive merge of `addend` into a fresh histogram. Both are
+ * normalized first, so legacy/short arrays are safe.
+ */
+export function mergeHistograms(target, addend) {
+    const left = normalizeHistogram(target);
+    const right = normalizeHistogram(addend);
+    for (let index = 0; index < HISTOGRAM_BUCKET_COUNT; index += 1) {
+        left[index] = (left[index] ?? 0) + (right[index] ?? 0);
+    }
+    return left;
+}
+/** Build a latency histogram from raw durations (ms). */
+export function buildHistogram(durations) {
+    const histogram = emptyHistogram();
+    for (const duration of durations)
+        incrementHistogram(histogram, duration);
+    return histogram;
+}
+/**
+ * Estimates a percentile from a pre-aggregated latency histogram (O(buckets), no
+ * raw scan). Nearest-rank style at BUCKET resolution: the result is the UPPER
+ * boundary of the bucket that contains the target rank, so the estimate is an
+ * APPROXIMATION whose error is bounded by that bucket's width.
+ *
+ * - `total = Σ histogram`; `target rank = ceil(fraction * total)` (1-based,
+ *   matching the raw nearest-rank `Math.ceil(fraction * n)`).
+ * - Walk the cumulative count until it reaches/crosses the target rank; return
+ *   the containing bucket's upper boundary.
+ * - The OVERFLOW bucket has no finite upper boundary; we return the LAST boundary
+ *   as a safe finite representative (documented under-estimate, never `Infinity`).
+ * - Returns 0 when the histogram is empty / total is 0.
+ */
+export function estimatePercentileFromHistogram(histogram, fraction) {
+    const cells = normalizeHistogram(histogram);
+    let total = 0;
+    for (const count of cells)
+        total += count;
+    if (total <= 0)
+        return 0;
+    const boundedFraction = Math.min(1, Math.max(0, fraction));
+    const targetRank = Math.max(1, Math.ceil(boundedFraction * total));
+    const lastBoundary = LATENCY_BOUNDARIES_MS[LATENCY_BOUNDARIES_MS.length - 1] ?? 0;
+    let cumulative = 0;
+    for (let index = 0; index < cells.length; index += 1) {
+        cumulative += cells[index] ?? 0;
+        if (cumulative >= targetRank) {
+            return LATENCY_BOUNDARIES_MS[index] ?? lastBoundary;
+        }
+    }
+    return lastBoundary;
+}
+//# sourceMappingURL=rollup.js.map

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

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

package/dist/src/metrics/stats.d.ts

@@ -0,0 +1,112 @@
+import { type Entry } from '../entry.js';
+import { type TimeseriesReport } from './timeseries.js';
+/**
+ * Per-type analytics over a window of stored entries. Ported from
+ * `nestjs-telescope`'s `metrics/stats.ts`, adapted to the Adonis entry content
+ * shapes (request `status`, cache `operation` enum + `key`, exception `name`).
+ * Pure: callers fetch the windowed entries and supply the window bounds.
+ */
+export interface LatencyStats {
+    count: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    max: number;
+    slow: number;
+}
+export interface FamilyLatency {
+    familyHash: string;
+    label: string;
+    count: number;
+    p50: number;
+    p99: number;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    sets: number;
+    hitRatio: number;
+    topKeys: {
+        key: string;
+        count: number;
+    }[];
+}
+export interface StatusBreakdown {
+    '2xx': number;
+    '3xx': number;
+    '4xx': number;
+    '5xx': number;
+    other: number;
+}
+export interface ExceptionGroupStats {
+    /** The family key — the entry's `familyHash` when present, else `${class}: ${message}`. */
+    key: string;
+    class: string;
+    message: string;
+    count: number;
+    /** Most recent occurrence in the window. */
+    lastAt: Date;
+    /** Per-bucket occurrence counts, aligned to the report's `overTime` buckets. */
+    overTime: number[];
+}
+export interface StatsResult {
+    type: string;
+    windowMs: number;
+    total: number;
+    /** Throughput over the window — reuses {@link bucketTimeseries}. */
+    overTime: TimeseriesReport;
+    /** Present for types whose entries carry a `durationMs`. */
+    latency?: LatencyStats;
+    /** Query only: top families by p99. */
+    families?: FamilyLatency[];
+    /** Cache only. */
+    cache?: CacheStats;
+    /** Request only. */
+    status?: StatusBreakdown;
+    /** Exception only: top groups by class+message, with count, last-seen, over-time. */
+    exceptions?: ExceptionGroupStats[];
+    /** Caller-supplied: whether the scan hit its cap. */
+    truncated: boolean;
+}
+/** Pre-estimated p50/p95/p99 (ms) supplied by a histogram-backed caller to
+ *  replace the raw-scan percentiles. count/max/slow stay raw. */
+export interface LatencyPercentilesOverride {
+    p50: number;
+    p95: number;
+    p99: number;
+}
+export interface SummarizeStatsInput {
+    entries: Entry[];
+    type: string;
+    windowStart: Date;
+    windowEnd: Date;
+    windowMs: number;
+    buckets: number;
+    slowMs: number;
+    truncated: boolean;
+    topFamilies?: number;
+    topKeys?: number;
+    topExceptions?: number;
+    /** When provided, p50/p95/p99 in the latency block are taken from these
+     *  histogram estimates instead of the raw-scan computation. */
+    latencyPercentiles?: LatencyPercentilesOverride;
+}
+/** Nearest-rank percentile over a NON-EMPTY ascending array; 0 for empty.
+ *  `q` in [0,1]; `idx = clamp(ceil(q*n)-1, 0, n-1)`. */
+export declare function percentile(sortedAscending: number[], q: number): number;
+/**
+ * Estimate p50/p95/p99 over a set of durations using the latency histogram,
+ * clamped to the exact max so a percentile is never reported above the observed
+ * maximum. Returns `undefined` when there are no samples (shape parity with the
+ * raw path's "no durations ⇒ no latency"). This is the storage-agnostic stand-in
+ * for the NestJS RollupStore fast path; the equivalence spec proves it agrees
+ * with the raw-scan percentile within one bucket-width.
+ */
+export declare function estimateLatencyPercentiles(durations: number[]): LatencyPercentilesOverride | undefined;
+/**
+ * Aggregate a window of entries into per-type analytics: latency percentiles,
+ * query-family breakdown, cache hit/miss, request status breakdown, exception
+ * groups, and a throughput time-series. Pure.
+ */
+export declare function summarizeStats(input: SummarizeStatsInput): StatsResult;
+//# sourceMappingURL=stats.d.ts.map

package/dist/src/metrics/stats.d.ts.map

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