@adonis-agora/telescope 0.2.0 → 0.3.0

package/dist/src/metrics/stats.js

@@ -0,0 +1,255 @@
+import { EntryType } from '../entry.js';
+import { buildHistogram, estimatePercentileFromHistogram } from './rollup.js';
+import { bucketTimeseries } from './timeseries.js';
+const DEFAULT_TOP_FAMILIES = 8;
+const DEFAULT_TOP_KEYS = 8;
+const DEFAULT_TOP_EXCEPTIONS = 8;
+const MAX_FAMILY_LABEL_LENGTH = 60;
+/** 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 function percentile(sortedAscending, q) {
+    const n = sortedAscending.length;
+    if (n === 0)
+        return 0;
+    const rawIndex = Math.ceil(q * n) - 1;
+    const index = Math.min(n - 1, Math.max(0, rawIndex));
+    return sortedAscending[index] ?? 0;
+}
+/**
+ * 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 function estimateLatencyPercentiles(durations) {
+    if (durations.length === 0)
+        return undefined;
+    const histogram = buildHistogram(durations);
+    const max = Math.max(...durations);
+    return {
+        p50: Math.min(estimatePercentileFromHistogram(histogram, 0.5), max),
+        p95: Math.min(estimatePercentileFromHistogram(histogram, 0.95), max),
+        p99: Math.min(estimatePercentileFromHistogram(histogram, 0.99), max),
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function computeLatency(entries, slowMs) {
+    const durations = [];
+    let slow = 0;
+    for (const entry of entries) {
+        if (typeof entry.durationMs === 'number') {
+            durations.push(entry.durationMs);
+            if (entry.durationMs >= slowMs)
+                slow += 1;
+        }
+    }
+    if (durations.length === 0)
+        return undefined;
+    durations.sort((a, b) => a - b);
+    return {
+        count: durations.length,
+        p50: percentile(durations, 0.5),
+        p95: percentile(durations, 0.95),
+        p99: percentile(durations, 0.99),
+        max: durations[durations.length - 1] ?? 0,
+        slow,
+    };
+}
+function queryLabel(content) {
+    if (isRecord(content) && typeof content.sql === 'string') {
+        return content.sql.slice(0, MAX_FAMILY_LABEL_LENGTH);
+    }
+    return '';
+}
+function computeFamilies(entries, topFamilies) {
+    const groups = new Map();
+    for (const entry of entries) {
+        if (entry.familyHash === null)
+            continue;
+        const existing = groups.get(entry.familyHash);
+        if (existing) {
+            if (typeof entry.durationMs === 'number')
+                existing.durations.push(entry.durationMs);
+        }
+        else {
+            groups.set(entry.familyHash, {
+                durations: typeof entry.durationMs === 'number' ? [entry.durationMs] : [],
+                label: queryLabel(entry.content),
+            });
+        }
+    }
+    const families = [];
+    for (const [familyHash, group] of groups) {
+        const durations = [...group.durations].sort((a, b) => a - b);
+        families.push({
+            familyHash,
+            label: group.label,
+            count: durations.length,
+            p50: percentile(durations, 0.5),
+            p99: percentile(durations, 0.99),
+        });
+    }
+    families.sort((a, b) => b.p99 - a.p99 || b.count - a.count || a.familyHash.localeCompare(b.familyHash));
+    return families.slice(0, topFamilies);
+}
+function computeCache(entries, topKeys) {
+    let hits = 0;
+    let misses = 0;
+    let sets = 0;
+    const keyCounts = new Map();
+    for (const entry of entries) {
+        const content = entry.content;
+        if (!isRecord(content))
+            continue;
+        const operation = content.operation;
+        if (typeof operation !== 'string')
+            continue;
+        const key = typeof content.key === 'string' ? content.key : null;
+        if (key !== null)
+            keyCounts.set(key, (keyCounts.get(key) ?? 0) + 1);
+        // Adonis cache ops: 'hit' | 'miss' | 'write' | 'delete' | 'clear'.
+        if (operation === 'write')
+            sets += 1;
+        else if (operation === 'hit')
+            hits += 1;
+        else if (operation === 'miss')
+            misses += 1;
+    }
+    const denominator = hits + misses;
+    const ranked = [...keyCounts.entries()]
+        .map(([key, count]) => ({ key, count }))
+        .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key))
+        .slice(0, topKeys);
+    return {
+        hits,
+        misses,
+        sets,
+        hitRatio: denominator === 0 ? 0 : hits / denominator,
+        topKeys: ranked,
+    };
+}
+/** The HTTP status code from a request entry's content (Adonis records `status`). */
+function statusOf(content) {
+    if (!isRecord(content))
+        return null;
+    const status = content.status;
+    return typeof status === 'number' ? status : null;
+}
+function computeStatus(entries) {
+    const breakdown = { '2xx': 0, '3xx': 0, '4xx': 0, '5xx': 0, other: 0 };
+    for (const entry of entries) {
+        const code = statusOf(entry.content);
+        if (code !== null && code >= 200 && code < 300)
+            breakdown['2xx'] += 1;
+        else if (code !== null && code >= 300 && code < 400)
+            breakdown['3xx'] += 1;
+        else if (code !== null && code >= 400 && code < 500)
+            breakdown['4xx'] += 1;
+        else if (code !== null && code >= 500 && code < 600)
+            breakdown['5xx'] += 1;
+        else
+            breakdown.other += 1;
+    }
+    return breakdown;
+}
+/** Adonis exception content fields (`name` is the error class, plus `message`). */
+function exceptionFields(content) {
+    if (!isRecord(content))
+        return null;
+    const className = typeof content.name === 'string' ? content.name : 'Error';
+    const message = typeof content.message === 'string' ? content.message : '';
+    return { class: className, message };
+}
+function exceptionKey(entry, fields) {
+    return entry.familyHash ?? `${fields.class}: ${fields.message}`;
+}
+/** The bucket index a timestamp falls into; mirrors {@link bucketTimeseries}. */
+function bucketIndexFor(createdAt, windowStart, windowEnd, bucketCount) {
+    const count = Math.max(1, Math.floor(bucketCount));
+    const startMs = windowStart.getTime();
+    const spanMs = Math.max(1, windowEnd.getTime() - startMs);
+    const bucketMs = Math.max(1, Math.floor(spanMs / count));
+    const rawIndex = Math.floor((createdAt.getTime() - startMs) / bucketMs);
+    return Math.min(count - 1, Math.max(0, rawIndex));
+}
+function computeExceptions(entries, windowStart, windowEnd, buckets, topExceptions) {
+    const bucketCount = Math.max(1, Math.floor(buckets));
+    const groups = new Map();
+    for (const entry of entries) {
+        const fields = exceptionFields(entry.content);
+        if (fields === null)
+            continue;
+        const key = exceptionKey(entry, fields);
+        const index = bucketIndexFor(entry.createdAt, windowStart, windowEnd, bucketCount);
+        const existing = groups.get(key);
+        if (existing) {
+            existing.count += 1;
+            if (entry.createdAt > existing.lastAt)
+                existing.lastAt = entry.createdAt;
+            existing.overTime[index] = (existing.overTime[index] ?? 0) + 1;
+        }
+        else {
+            const overTime = new Array(bucketCount).fill(0);
+            overTime[index] = 1;
+            groups.set(key, {
+                class: fields.class,
+                message: fields.message,
+                count: 1,
+                lastAt: entry.createdAt,
+                overTime,
+            });
+        }
+    }
+    return [...groups.entries()]
+        .map(([key, group]) => ({ key, ...group }))
+        .sort((a, b) => b.count - a.count || b.lastAt.getTime() - a.lastAt.getTime() || a.key.localeCompare(b.key))
+        .slice(0, topExceptions);
+}
+/**
+ * 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 function summarizeStats(input) {
+    const { entries, type, windowStart, windowEnd, windowMs, buckets, slowMs, truncated, topFamilies = DEFAULT_TOP_FAMILIES, topKeys = DEFAULT_TOP_KEYS, topExceptions = DEFAULT_TOP_EXCEPTIONS, latencyPercentiles, } = input;
+    const overTime = bucketTimeseries(entries, windowStart, windowEnd, buckets);
+    const latency = computeLatency(entries, slowMs);
+    const result = {
+        type,
+        windowMs,
+        total: entries.length,
+        overTime,
+        truncated,
+    };
+    // When the caller supplied histogram percentile estimates, substitute
+    // p50/p95/p99 (count/max/slow stay raw-derived). This only fires when the raw
+    // scan also found latency samples, keeping the "no durations ⇒ no latency"
+    // shape identical to the pure raw path.
+    if (latency !== undefined && latencyPercentiles !== undefined) {
+        latency.p50 = latencyPercentiles.p50;
+        latency.p95 = latencyPercentiles.p95;
+        latency.p99 = latencyPercentiles.p99;
+    }
+    if (latency !== undefined)
+        result.latency = latency;
+    if (type === EntryType.Query) {
+        const families = computeFamilies(entries, topFamilies);
+        if (families.length > 0)
+            result.families = families;
+    }
+    if (type === EntryType.Cache)
+        result.cache = computeCache(entries, topKeys);
+    if (type === EntryType.Request)
+        result.status = computeStatus(entries);
+    if (type === EntryType.Exception) {
+        const exceptions = computeExceptions(entries, windowStart, windowEnd, buckets, topExceptions);
+        if (exceptions.length > 0)
+            result.exceptions = exceptions;
+    }
+    return result;
+}
+//# sourceMappingURL=stats.js.map

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

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

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

@@ -0,0 +1,22 @@
+import type { Entry } from '../entry.js';
+/** A single time-bucket of a {@link TimeseriesReport}. */
+export interface TimeseriesBucket {
+    /** ISO timestamp of the bucket's start. */
+    t: string;
+    total: number;
+    byType: Record<string, number>;
+}
+export interface TimeseriesReport {
+    windowStart: string;
+    windowEnd: string;
+    bucketMs: number;
+    buckets: TimeseriesBucket[];
+}
+/**
+ * Group entries into `bucketCount` equal time buckets across [windowStart,
+ * windowEnd], counting total + per-type per bucket. Ported from `nestjs-telescope`'s
+ * `metrics/timeseries.ts`. Pure: callers fetch the windowed entries.
+ * Out-of-range entries are clamped into the edge buckets.
+ */
+export declare function bucketTimeseries(entries: Entry[], windowStart: Date, windowEnd: Date, bucketCount: number): TimeseriesReport;
+//# sourceMappingURL=timeseries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeseries.d.ts","sourceRoot":"","sources":["../../../src/metrics/timeseries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,0DAA0D;AAC1D,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,EAAE,EAChB,WAAW,EAAE,IAAI,EACjB,SAAS,EAAE,IAAI,EACf,WAAW,EAAE,MAAM,GAClB,gBAAgB,CA4BlB"}

package/dist/src/metrics/timeseries.js

@@ -0,0 +1,34 @@
+/**
+ * Group entries into `bucketCount` equal time buckets across [windowStart,
+ * windowEnd], counting total + per-type per bucket. Ported from `nestjs-telescope`'s
+ * `metrics/timeseries.ts`. Pure: callers fetch the windowed entries.
+ * Out-of-range entries are clamped into the edge buckets.
+ */
+export function bucketTimeseries(entries, windowStart, windowEnd, bucketCount) {
+    const count = Math.max(1, Math.floor(bucketCount));
+    const startMs = windowStart.getTime();
+    const spanMs = Math.max(1, windowEnd.getTime() - startMs);
+    const bucketMs = Math.max(1, Math.floor(spanMs / count));
+    const buckets = Array.from({ length: count }, (_, index) => ({
+        t: new Date(startMs + index * bucketMs).toISOString(),
+        total: 0,
+        byType: {},
+    }));
+    for (const entry of entries) {
+        const offset = entry.createdAt.getTime() - startMs;
+        const rawIndex = Math.floor(offset / bucketMs);
+        const index = Math.min(count - 1, Math.max(0, rawIndex));
+        const bucket = buckets[index];
+        if (!bucket)
+            continue;
+        bucket.total += 1;
+        bucket.byType[entry.type] = (bucket.byType[entry.type] ?? 0) + 1;
+    }
+    return {
+        windowStart: windowStart.toISOString(),
+        windowEnd: windowEnd.toISOString(),
+        bucketMs,
+        buckets,
+    };
+}
+//# sourceMappingURL=timeseries.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeseries.js","sourceRoot":"","sources":["../../../src/metrics/timeseries.ts"],"names":[],"mappings":"AAiBA;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAgB,EAChB,WAAiB,EACjB,SAAe,EACf,WAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,EAAE,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC;IAEzD,MAAM,OAAO,GAAuB,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAC/E,CAAC,EAAE,IAAI,IAAI,CAAC,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC,CAAC,WAAW,EAAE;QACrD,KAAK,EAAE,CAAC;QACR,MAAM,EAAE,EAAE;KACX,CAAC,CAAC,CAAC;IAEJ,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC;QACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC;QAClB,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IACnE,CAAC;IAED,OAAO;QACL,WAAW,EAAE,WAAW,CAAC,WAAW,EAAE;QACtC,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE;QAClC,QAAQ;QACR,OAAO;KACR,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,27 @@
+import { type Entry } from '../entry.js';
+/** A per-trace summary row for the dashboard's trace list. */
+export interface TraceSummary {
+    traceId: string;
+    /** Number of entries that share this traceId. */
+    entryCount: number;
+    /** Distinct entry types in the trace, sorted ascending. */
+    types: string[];
+    /** Earliest `createdAt` across the trace's entries. */
+    firstAt: Date;
+    /** Latest `createdAt` across the trace's entries. */
+    lastAt: Date;
+    /** Sum of non-null `durationMs` across the trace's entries. */
+    totalDurationMs: number;
+    /** The request entry's "METHOD url" label, when the trace has one. */
+    rootLabel?: string;
+}
+export interface SummarizeTracesOptions {
+    limit?: number;
+}
+/**
+ * Groups window entries by `traceId` (null trace ids skipped) into a summary per
+ * distinct trace, sorted by `lastAt` desc and sliced to `limit`. Ported from
+ * `nestjs-telescope`'s `metrics/traces.ts`. Pure.
+ */
+export declare function summarizeTraces(entries: Entry[], options?: SummarizeTracesOptions): TraceSummary[];
+//# sourceMappingURL=traces.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"traces.d.ts","sourceRoot":"","sources":["../../../src/metrics/traces.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,aAAa,CAAC;AAEpD,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uDAAuD;IACvD,OAAO,EAAE,IAAI,CAAC;IACd,qDAAqD;IACrD,MAAM,EAAE,IAAI,CAAC;IACb,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyBD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,KAAK,EAAE,EAChB,OAAO,GAAE,sBAA2B,GACnC,YAAY,EAAE,CAqDhB"}

package/dist/src/metrics/traces.js

@@ -0,0 +1,71 @@
+import { EntryType } from '../entry.js';
+const DEFAULT_LIMIT = 50;
+/** Narrows an entry's content to a request label (`METHOD url`). The Adonis
+ *  request watcher records `{ method, url }` content. */
+function asRequestLabel(content) {
+    if (typeof content !== 'object' || content === null)
+        return undefined;
+    const record = content;
+    const url = typeof record.url === 'string' ? record.url : undefined;
+    if (url === undefined)
+        return undefined;
+    const method = typeof record.method === 'string' ? record.method : undefined;
+    return method !== undefined ? `${method} ${url}` : url;
+}
+/**
+ * Groups window entries by `traceId` (null trace ids skipped) into a summary per
+ * distinct trace, sorted by `lastAt` desc and sliced to `limit`. Ported from
+ * `nestjs-telescope`'s `metrics/traces.ts`. Pure.
+ */
+export function summarizeTraces(entries, options = {}) {
+    const limit = Math.max(0, Math.floor(options.limit ?? DEFAULT_LIMIT));
+    const byTrace = new Map();
+    for (const entry of entries) {
+        const traceId = entry.traceId;
+        if (traceId === null)
+            continue;
+        let accumulator = byTrace.get(traceId);
+        if (accumulator === undefined) {
+            accumulator = {
+                traceId,
+                entryCount: 0,
+                types: new Set(),
+                firstAt: entry.createdAt,
+                lastAt: entry.createdAt,
+                totalDurationMs: 0,
+            };
+            byTrace.set(traceId, accumulator);
+        }
+        accumulator.entryCount += 1;
+        accumulator.types.add(entry.type);
+        if (entry.createdAt.getTime() < accumulator.firstAt.getTime()) {
+            accumulator.firstAt = entry.createdAt;
+        }
+        if (entry.createdAt.getTime() > accumulator.lastAt.getTime()) {
+            accumulator.lastAt = entry.createdAt;
+        }
+        if (entry.durationMs !== null) {
+            accumulator.totalDurationMs += entry.durationMs;
+        }
+        if (accumulator.rootLabel === undefined && entry.type === EntryType.Request) {
+            const label = asRequestLabel(entry.content);
+            if (label !== undefined)
+                accumulator.rootLabel = label;
+        }
+    }
+    const summaries = [];
+    for (const accumulator of byTrace.values()) {
+        summaries.push({
+            traceId: accumulator.traceId,
+            entryCount: accumulator.entryCount,
+            types: [...accumulator.types].sort(),
+            firstAt: accumulator.firstAt,
+            lastAt: accumulator.lastAt,
+            totalDurationMs: accumulator.totalDurationMs,
+            ...(accumulator.rootLabel !== undefined ? { rootLabel: accumulator.rootLabel } : {}),
+        });
+    }
+    summaries.sort((a, b) => b.lastAt.getTime() - a.lastAt.getTime());
+    return summaries.slice(0, limit);
+}
+//# sourceMappingURL=traces.js.map

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

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

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

@@ -0,0 +1,44 @@
+import { type Entry } from '../entry.js';
+/**
+ * A single node in a trace waterfall. Offsets are relative to the trace's
+ * earliest start so the UI can lay each bar out as
+ * `left = offsetMs / totalDurationMs`, `width = durationMs / totalDurationMs`.
+ */
+export interface WaterfallSpan {
+    id: string;
+    type: string;
+    /** A human label derived from the entry's content (route, sql, queue:job, …). */
+    label: string;
+    /** Start offset (ms) from the trace start. */
+    offsetMs: number;
+    /** Span duration (ms); a null `durationMs` becomes a zero-width instant span. */
+    durationMs: number;
+    /** Nesting depth (0 for roots). */
+    depth: number;
+    /** Stable record order within the trace (the entry's `sequence`). */
+    sequence: number;
+    children: WaterfallSpan[];
+}
+export interface Waterfall {
+    /** Absolute trace start (epoch ms) — the earliest entry start. */
+    traceStartMs: number;
+    /** Wall-clock span of the whole trace (latest end − earliest start), >= 0. */
+    totalDurationMs: number;
+    /** Root spans (those not contained by any other), ordered by start then sequence. */
+    spans: WaterfallSpan[];
+}
+/**
+ * Reconstruct a nested span waterfall from a trace's entries. Ported from
+ * `nestjs-telescope`'s `metrics/waterfall.ts`.
+ *
+ * DESIGN: the entry model carries `traceId` but NOT a parent-span pointer, so we
+ * cannot rebuild the exact span tree from explicit links. Instead — exactly as
+ * Sentry/Tempo do when parent links are missing — we infer nesting from
+ * **time-interval containment**: a span is a child of the tightest enclosing span
+ * whose `[start, end]` strictly contains it. `sequence` provides a stable
+ * tie-break for spans that start at the same instant.
+ *
+ * Returns `null` for an empty input. Pure.
+ */
+export declare function buildWaterfall(entries: Entry[]): Waterfall | null;
+//# sourceMappingURL=waterfall.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"waterfall.d.ts","sourceRoot":"","sources":["../../../src/metrics/waterfall.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAa,MAAM,aAAa,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,eAAe,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAkCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,SAAS,GAAG,IAAI,CAwDjE"}

package/dist/src/metrics/waterfall.js

@@ -0,0 +1,99 @@
+import { EntryType } from '../entry.js';
+function asRecord(content) {
+    return typeof content === 'object' && content !== null
+        ? content
+        : null;
+}
+/** A human label for a span, derived from the entry's content by type. */
+function labelFor(entry) {
+    const record = asRecord(entry.content);
+    if (record === null)
+        return 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}`;
+    }
+    if (entry.type === EntryType.HttpClient && typeof record.url === 'string') {
+        return typeof record.method === 'string' ? `${record.method} ${record.url}` : record.url;
+    }
+    if (typeof record.name === 'string')
+        return record.name;
+    return entry.type;
+}
+/**
+ * Reconstruct a nested span waterfall from a trace's entries. Ported from
+ * `nestjs-telescope`'s `metrics/waterfall.ts`.
+ *
+ * DESIGN: the entry model carries `traceId` but NOT a parent-span pointer, so we
+ * cannot rebuild the exact span tree from explicit links. Instead — exactly as
+ * Sentry/Tempo do when parent links are missing — we infer nesting from
+ * **time-interval containment**: a span is a child of the tightest enclosing span
+ * whose `[start, end]` strictly contains it. `sequence` provides a stable
+ * tie-break for spans that start at the same instant.
+ *
+ * Returns `null` for an empty input. Pure.
+ */
+export function buildWaterfall(entries) {
+    if (entries.length === 0)
+        return null;
+    const intervals = entries.map((entry) => {
+        const startMs = entry.createdAt.getTime();
+        const durationMs = typeof entry.durationMs === 'number' ? Math.max(0, entry.durationMs) : 0;
+        return { entry, startMs, durationMs, endMs: startMs + durationMs };
+    });
+    const traceStartMs = Math.min(...intervals.map((i) => i.startMs));
+    const traceEndMs = Math.max(...intervals.map((i) => i.endMs));
+    const totalDurationMs = Math.max(0, traceEndMs - traceStartMs);
+    // Order so that enclosing spans come first: earliest start, then the LONGER
+    // span first (a parent starts no later and ends no earlier than its child),
+    // then sequence for a stable tie-break.
+    const ordered = [...intervals].sort((a, b) => a.startMs - b.startMs || b.durationMs - a.durationMs || a.entry.sequence - b.entry.sequence);
+    const nodeById = new Map();
+    const roots = [];
+    const openStack = [];
+    for (const interval of ordered) {
+        while (openStack.length > 0) {
+            const top = openStack[openStack.length - 1];
+            if (top !== undefined && contains(top.interval, interval))
+                break;
+            openStack.pop();
+        }
+        const parent = openStack[openStack.length - 1];
+        const depth = parent === undefined ? 0 : parent.node.depth + 1;
+        const node = {
+            id: interval.entry.id,
+            type: interval.entry.type,
+            label: labelFor(interval.entry),
+            offsetMs: interval.startMs - traceStartMs,
+            durationMs: interval.durationMs,
+            depth,
+            sequence: interval.entry.sequence,
+            children: [],
+        };
+        nodeById.set(node.id, node);
+        if (parent === undefined)
+            roots.push(node);
+        else
+            parent.node.children.push(node);
+        openStack.push({ interval, node });
+    }
+    // Order children (and roots) by start offset, then sequence.
+    const byOffset = (a, b) => a.offsetMs - b.offsetMs || a.sequence - b.sequence;
+    for (const node of nodeById.values())
+        node.children.sort(byOffset);
+    roots.sort(byOffset);
+    return { traceStartMs, totalDurationMs, spans: roots };
+}
+/** True when `outer` strictly encloses `inner` — contains the interval AND is
+ *  genuinely larger on at least one side. Two spans with the SAME interval are
+ *  siblings, not nested; a zero-width child inside a parent's bounds still nests. */
+function contains(outer, inner) {
+    const encloses = outer.startMs <= inner.startMs && outer.endMs >= inner.endMs;
+    const strictlyLarger = outer.startMs < inner.startMs || outer.endMs > inner.endMs;
+    return encloses && strictlyLarger;
+}
+//# sourceMappingURL=waterfall.js.map

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

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