apm-optima 1.0.4 → 2.0.0

package/dist/core/telemetry/incident.service.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IncidentService = exports.CAUSE_NOTE = exports.initialTracker = void 0;
+exports.stepRule = stepRule;
+exports.defaultIncidentRules = defaultIncidentRules;
+const bucket_metric_1 = require("../storage/stores/bucket-metric");
+const initialTracker = () => ({ state: 'NORMAL', sinceMs: null, breachStartMs: null, recoveryStartMs: null });
+exports.initialTracker = initialTracker;
+function stepRule(t, obs, rule, timing) {
+    const now = obs.endMs;
+    const valid = obs.valid && obs.value !== null;
+    const breach = valid && obs.value > rule.threshold;
+    switch (t.state) {
+        case 'NORMAL':
+            return breach ? { state: 'PENDING', sinceMs: now, breachStartMs: now, recoveryStartMs: null } : t;
+        case 'PENDING':
+            if (!breach)
+                return { state: 'NORMAL', sinceMs: now, breachStartMs: null, recoveryStartMs: null };
+            if (now - t.breachStartMs >= timing.pendingForMs) {
+                return { state: 'FIRING', sinceMs: now, breachStartMs: t.breachStartMs, recoveryStartMs: null };
+            }
+            return t;
+        case 'FIRING': {
+            if (!valid || obs.value > rule.recoverBelow)
+                return { ...t, recoveryStartMs: null };
+            const recoveryStartMs = t.recoveryStartMs ?? now;
+            if (now - recoveryStartMs >= timing.recoveryForMs) {
+                return { state: 'RESOLVED', sinceMs: now, breachStartMs: null, recoveryStartMs: null };
+            }
+            return { ...t, recoveryStartMs };
+        }
+        case 'RESOLVED':
+            if (breach)
+                return { state: 'PENDING', sinceMs: now, breachStartMs: now, recoveryStartMs: null };
+            if (now - (t.sinceMs ?? now) >= timing.resolvedHoldMs) {
+                return { state: 'NORMAL', sinceMs: now, breachStartMs: null, recoveryStartMs: null };
+            }
+            return t;
+    }
+}
+function completeWindow(w, windowIntervals) {
+    if (w.total.bucketCount < windowIntervals)
+        return 'INCOMPLETE_WINDOW';
+    if (w.issues.some(i => i.type === 'GAP'))
+        return 'GAPS';
+    return undefined;
+}
+function defaultIncidentRules(o) {
+    const requestWindow = (w) => {
+        const incomplete = completeWindow(w, o.windowIntervals);
+        if (incomplete)
+            return incomplete;
+        if (w.total.requests.requestCount < o.minRequests)
+            return 'TOO_FEW_REQUESTS';
+        return undefined;
+    };
+    return [
+        {
+            id: 'server-error-rate',
+            title: 'High server error rate (5xx)',
+            metric: 'errorRate',
+            unit: '%',
+            severity: 'critical',
+            threshold: o.serverErrorRate * 100,
+            recoverBelow: o.serverErrorRate * 100 * o.recoveryRatio,
+            measure: w => {
+                const reason = requestWindow(w);
+                if (reason)
+                    return { valid: false, value: null, reason };
+                const r = w.total.requests;
+                return { valid: true, value: (r.serverErrorCount / r.requestCount) * 100 };
+            },
+        },
+        {
+            id: 'p95-latency',
+            title: 'High p95 latency',
+            metric: 'p95Latency',
+            unit: 'ms',
+            severity: 'warning',
+            threshold: o.p95LatencyMs,
+            recoverBelow: o.p95LatencyMs * o.recoveryRatio,
+            measure: w => {
+                const reason = requestWindow(w);
+                if (reason)
+                    return { valid: false, value: null, reason };
+                return { valid: true, value: (0, bucket_metric_1.deriveMetrics)(w.total.requests, w.total.durationMs).p95 };
+            },
+        },
+        {
+            id: 'event-loop-lag',
+            title: 'High event loop lag',
+            metric: 'eventLoopLag',
+            unit: 'ms',
+            severity: 'warning',
+            threshold: o.eventLoopLagMs,
+            recoverBelow: o.eventLoopLagMs * o.recoveryRatio,
+            measure: w => {
+                const incomplete = completeWindow(w, o.windowIntervals);
+                if (incomplete)
+                    return { valid: false, value: null, reason: incomplete };
+                const runtime = (0, bucket_metric_1.emptyRuntime)();
+                for (const p of w.points)
+                    (0, bucket_metric_1.mergeRuntimeInto)(runtime, p.runtime, true);
+                const mean = (0, bucket_metric_1.deriveRuntime)(runtime, w.total.durationMs).eventLoopDelayMeanMs;
+                return mean === null
+                    ? { valid: false, value: null, reason: 'NO_EVENT_LOOP_SAMPLES' }
+                    : { valid: true, value: mean };
+            },
+        },
+    ];
+}
+exports.CAUSE_NOTE = 'Related findings show which metrics changed together during the incident. Correlation does not establish the cause.';
+class IncidentService {
+    deps;
+    timing;
+    windowIntervals;
+    historySize;
+    entries;
+    history = [];
+    lastSequence = null;
+    lastSessionId = null;
+    constructor(deps, options) {
+        this.deps = deps;
+        this.timing = {
+            pendingForMs: options.pendingForMs,
+            recoveryForMs: options.recoveryForMs,
+            resolvedHoldMs: options.resolvedHoldMs,
+        };
+        this.windowIntervals = options.windowIntervals;
+        this.historySize = options.historySize;
+        const rules = options.rules ?? defaultIncidentRules(options);
+        this.entries = rules.map(rule => ({ rule, tracker: (0, exports.initialTracker)(), last: null, incident: null }));
+    }
+    tick() {
+        this.evaluate();
+    }
+    evaluate() {
+        const sessionId = this.deps.sessionId();
+        if (sessionId !== this.lastSessionId) {
+            this.lastSessionId = sessionId;
+            this.lastSequence = null;
+            for (const e of this.entries) {
+                e.tracker = (0, exports.initialTracker)();
+                e.last = null;
+                e.incident = null;
+            }
+        }
+        const window = this.deps.queries.recent(this.windowIntervals, {
+            consistency: this.deps.durable() ? 'committed' : 'live',
+        });
+        const last = window.points[window.points.length - 1];
+        if (!last || last.sequenceTo === this.lastSequence)
+            return false;
+        this.lastSequence = last.sequenceTo;
+        const endMs = Date.parse(last.endTime);
+        for (const entry of this.entries) {
+            const obs = { ...entry.rule.measure(window), endMs };
+            const prev = entry.tracker;
+            entry.tracker = stepRule(prev, obs, entry.rule, this.timing);
+            entry.last = obs;
+            this.apply(entry, prev.state, window, sessionId);
+        }
+        return true;
+    }
+    snapshot() {
+        const iso = (ms) => ms === null ? null : new Date(ms).toISOString();
+        const rules = this.entries.map(({ rule, tracker, last, incident }) => ({
+            ruleId: rule.id,
+            title: rule.title,
+            metric: rule.metric,
+            unit: rule.unit,
+            severity: rule.severity,
+            state: tracker.state,
+            since: iso(tracker.sinceMs),
+            value: last?.value ?? null,
+            threshold: rule.threshold,
+            recoverBelow: rule.recoverBelow,
+            valid: last?.valid ?? false,
+            reason: last?.reason,
+            incidentId: incident?.incidentId ?? null,
+        }));
+        const incidents = [...this.history].sort((a, b) => (a.status === b.status ? 0 : a.status === 'FIRING' ? -1 : 1) || b.firedAt.localeCompare(a.firedAt));
+        return { rules, incidents, serverTime: new Date().toISOString() };
+    }
+    apply(entry, prevState, window, sessionId) {
+        const { rule, tracker, last } = entry;
+        const value = last?.valid ? last.value : null;
+        if (prevState !== 'FIRING' && tracker.state === 'FIRING') {
+            const first = window.points[0];
+            const lastPoint = window.points[window.points.length - 1];
+            const incident = {
+                incidentId: `${sessionId}:${rule.id}:${lastPoint.sequenceTo}`,
+                sessionId,
+                ruleId: rule.id,
+                title: rule.title,
+                metric: rule.metric,
+                unit: rule.unit,
+                severity: rule.severity,
+                status: 'FIRING',
+                threshold: rule.threshold,
+                recoverBelow: rule.recoverBelow,
+                breachStartedAt: new Date(tracker.breachStartMs).toISOString(),
+                firedAt: new Date(tracker.sinceMs).toISOString(),
+                resolvedAt: null,
+                peakValue: value ?? rule.threshold,
+                lastValue: value,
+                sequenceFrom: first.sequenceFrom,
+                sequenceTo: lastPoint.sequenceTo,
+                relatedFindings: this.deps.related?.(rule.metric) ?? [],
+                causeNote: exports.CAUSE_NOTE,
+            };
+            entry.incident = incident;
+            this.history.push(incident);
+            if (this.history.length > this.historySize)
+                this.history.splice(0, this.history.length - this.historySize);
+            void this.deps.emit?.({ type: 'INCIDENT_OPENED', reason: `${rule.title}`, details: { ...incident } });
+            return;
+        }
+        const incident = entry.incident;
+        if (!incident)
+            return;
+        if (tracker.state === 'FIRING') {
+            if (value !== null) {
+                incident.lastValue = value;
+                incident.peakValue = Math.max(incident.peakValue, value);
+            }
+            return;
+        }
+        if (prevState === 'FIRING' && tracker.state === 'RESOLVED') {
+            incident.status = 'RESOLVED';
+            incident.resolvedAt = new Date(tracker.sinceMs).toISOString();
+            if (value !== null)
+                incident.lastValue = value;
+            entry.incident = null;
+            void this.deps.emit?.({ type: 'INCIDENT_RESOLVED', reason: `${rule.title}`, details: { ...incident } });
+        }
+    }
+}
+exports.IncidentService = IncidentService;

package/dist/core/telemetry/logger.d.ts

@@ -3,6 +3,10 @@ declare class Logger {
     private static readonly RESET;
     private static readonly BOLD;
     private static readonly DIM;
+    private static consoleLog;
+    static configure(options: {
+        consoleLog: boolean;
+    }): void;
     private static readonly COLORS;
     static log(req: Request, res: Response, duration: number): void;
     static error(message: string, ...args: unknown[]): void;

package/dist/core/telemetry/logger.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const config_1 = require("../../config");
 class Logger {
     static RESET = '\x1b[0m';
     static BOLD = '\x1b[1m';
     static DIM = '\x1b[2m';
+    static consoleLog = true;
+    static configure(options) {
+        Logger.consoleLog = options.consoleLog;
+    }
     static COLORS = {
         GET: '\x1b[32m', // Green
         POST: '\x1b[36m', // Cyan
@@ -16,7 +19,7 @@ class Logger {
         ERROR: '\x1b[31m' // Red (5xx)
     };
     static log(req, res, duration) {
-        if (!(0, config_1.getConfig)().consoleLog)
+        if (!Logger.consoleLog)
             return;
         const timestamp = new Date().toISOString().split('T')[1].slice(0, -1);
         const timeFormatted = `${duration.toFixed(2)}ms`.padStart(8, ' ');

package/dist/core/telemetry/runtime.service.d.ts

@@ -0,0 +1,14 @@
+import type { ReadonlyConfig } from "../../config";
+import type { HealthDetails, SystemStaticInfo } from "../domain";
+import type { LocalRepository } from "../storage";
+export declare class RuntimeService {
+    private readonly storage;
+    private readonly config;
+    readonly eventLoopLagThresholdMs: number;
+    readonly env: string;
+    readonly startedAt: number;
+    readonly nodeVersion: string;
+    constructor(storage: LocalRepository, config: ReadonlyConfig);
+    getSystemStaticInfo(): SystemStaticInfo;
+    get(): HealthDetails;
+}

package/dist/core/telemetry/runtime.service.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeService = void 0;
+class RuntimeService {
+    storage;
+    config;
+    eventLoopLagThresholdMs;
+    env;
+    startedAt;
+    nodeVersion;
+    constructor(storage, config) {
+        this.storage = storage;
+        this.config = config;
+        this.eventLoopLagThresholdMs = config.thresholds.eventLoopLagMs;
+        this.env = process.env.NODE_ENV ?? 'unknown';
+        this.nodeVersion = process.version;
+        this.startedAt = Date.now();
+    }
+    getSystemStaticInfo() {
+        return {
+            uptime: Date.now() - this.startedAt,
+            nodeVersion: this.nodeVersion,
+            env: this.env
+        };
+    }
+    get() {
+        const details = this.storage.runtime.details();
+        const gc = details.gc;
+        return {
+            cpu: {
+                numberOfCores: details.numberOfCores,
+                perCoreUsage: details.perCoreUsage,
+            },
+            memory: {
+                rssMemoryTotal: details.rssMemoryTotal,
+                externalMemory: details.externalMemory,
+            },
+            eventLoop: {
+                threshold: this.eventLoopLagThresholdMs,
+            },
+            handles: details.handles,
+            garbageCollection: {
+                gcCount: gc.gcCount,
+                gcTime: gc.gcTime,
+                gcPauseAverage: gc.gcCount > 0 ? parseFloat((gc.gcTime / gc.gcCount).toFixed(2)) : 0,
+                minorGC: gc.minorGC,
+                majorGC: gc.majorGC,
+                incrementalGC: gc.incrementalGC,
+                heapSpaces: gc.heapSpaces,
+                gcTotals: gc.gcTotals,
+            },
+            runtime: details.runtime,
+        };
+    }
+}
+exports.RuntimeService = RuntimeService;

package/dist/core/telemetry/telemetry-query.service.d.ts

@@ -0,0 +1,82 @@
+import { deriveMetrics, type MetricBucket, type RequestAggregate, type EndpointAggregate, type RuntimeInterval } from "../storage/stores/bucket-metric";
+export type MetricsQuery = {
+    sessionId: string;
+    from: string;
+    to: string;
+    method?: string;
+    route?: string;
+    resolutionMs?: number;
+    consistency: 'committed' | 'live';
+    includeEndpoints?: boolean;
+};
+export type QueryIssue = {
+    type: 'CONFLICT';
+    bucketId: string;
+} | {
+    type: 'GAP';
+    fromSequence: number;
+    toSequence: number;
+} | {
+    type: 'OUT_OF_ORDER';
+    bucketId: string;
+} | {
+    type: 'SOURCE_ERROR';
+    detail: string;
+};
+export interface SeriesPoint {
+    startTime: string;
+    endTime: string;
+    durationMs: number;
+    bucketCount: number;
+    sequenceFrom: number;
+    sequenceTo: number;
+    requests: RequestAggregate;
+    maxRps: number;
+    endpoints?: EndpointAggregate[];
+    runtime: RuntimeInterval;
+    qualityFlags: string[];
+    committed: boolean | null;
+}
+export interface MetricsQueryResult {
+    query: MetricsQuery;
+    points: SeriesPoint[];
+    total: {
+        requests: RequestAggregate;
+        durationMs: number;
+        bucketCount: number;
+        maxRps: number;
+        derived: ReturnType<typeof deriveMetrics>;
+    };
+    issues: QueryIssue[];
+    complete: boolean;
+}
+export interface CommittedBucketSource {
+    read(sessionId: string, fromMs: number, toMs: number, onIssue: (issue: QueryIssue) => void): AsyncIterable<MetricBucket>;
+}
+export interface LiveBucketEntry {
+    bucket: MetricBucket;
+    committed: boolean;
+}
+export interface LiveBucketSource {
+    snapshot(): LiveBucketEntry[];
+}
+export interface TelemetryQueryDeps {
+    committed: CommittedBucketSource;
+    live: LiveBucketSource;
+    currentSessionId: () => string;
+}
+export declare class TelemetryQueryService {
+    private readonly deps;
+    constructor(deps: TelemetryQueryDeps);
+    query(q: MetricsQuery): Promise<MetricsQueryResult>;
+    recent(count: number, opts?: Partial<Pick<MetricsQuery, 'consistency' | 'method' | 'route' | 'resolutionMs' | 'includeEndpoints'>>): MetricsQueryResult;
+    latestWindow(count: number, consistency: MetricsQuery['consistency']): {
+        sessionId: string;
+        from: string;
+        to: string;
+        sequenceFrom: number;
+        sequenceTo: number;
+    } | null;
+    liveBucket(sequence: number): MetricBucket | undefined;
+    buckets(q: MetricsQuery, onIssue: (i: QueryIssue) => void): AsyncGenerator<LiveBucketEntry>;
+}

package/dist/core/telemetry/telemetry-query.service.js

@@ -0,0 +1,231 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelemetryQueryService = void 0;
+const bucket_metric_1 = require("../storage/stores/bucket-metric");
+function stableStringify(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(',')}]`;
+    const o = v;
+    return `{${Object.keys(o).sort().map(k => `${JSON.stringify(k)}:${stableStringify(o[k])}`).join(',')}}`;
+}
+const fingerprint = (b) => stableStringify(b);
+function parseRange(q) {
+    const fromMs = Date.parse(q.from);
+    const toMs = Date.parse(q.to);
+    if (Number.isNaN(fromMs) || Number.isNaN(toMs))
+        throw new RangeError('Invalid time range');
+    if (fromMs > toMs)
+        throw new RangeError('`from` must not be after `to`');
+    return { fromMs, toMs };
+}
+const overlaps = (b, fromMs, toMs) => Date.parse(b.startTime) <= toMs && Date.parse(b.endTime) >= fromMs;
+function project(b, q) {
+    if (!q.method && !q.route)
+        return { requests: b.requests, endpoints: b.endpoints };
+    const matching = b.endpoints.filter(e => (!q.method || e.method === q.method) && (!q.route || e.route === q.route));
+    const requests = (0, bucket_metric_1.createAggregate)();
+    for (const e of matching)
+        (0, bucket_metric_1.mergeInto)(requests, e);
+    return { requests, endpoints: matching };
+}
+class SeriesAccumulator {
+    q;
+    issues;
+    groups = new Map();
+    total = (0, bucket_metric_1.createAggregate)();
+    totalDurationMs = 0;
+    maxRps = 0;
+    bucketCount = 0;
+    prevSequence = null;
+    constructor(q, issues) {
+        this.q = q;
+        this.issues = issues;
+    }
+    add(b, committed) {
+        if (this.prevSequence !== null) {
+            if (b.sequence <= this.prevSequence) {
+                this.issues.push({ type: 'OUT_OF_ORDER', bucketId: b.bucketId });
+            }
+            else if (b.sequence > this.prevSequence + 1) {
+                this.issues.push({ type: 'GAP', fromSequence: this.prevSequence + 1, toSequence: b.sequence - 1 });
+            }
+        }
+        this.prevSequence = this.prevSequence === null ? b.sequence : Math.max(this.prevSequence, b.sequence);
+        const p = project(b, this.q);
+        this.bucketCount++;
+        this.totalDurationMs += b.durationMs;
+        (0, bucket_metric_1.mergeInto)(this.total, p.requests);
+        const bucketRps = (0, bucket_metric_1.deriveMetrics)(p.requests, b.durationMs).rps;
+        this.maxRps = Math.max(this.maxRps, bucketRps);
+        const size = this.q.resolutionMs && this.q.resolutionMs > 0 ? this.q.resolutionMs : 0;
+        const key = size ? Math.floor(Date.parse(b.startTime) / size) : b.sequence;
+        let g = this.groups.get(key);
+        if (!g) {
+            g = {
+                startTime: b.startTime, endTime: b.endTime,
+                durationMs: 0, bucketCount: 0,
+                sequenceFrom: b.sequence, sequenceTo: b.sequence,
+                requests: (0, bucket_metric_1.createAggregate)(),
+                maxRps: 0,
+                endpoints: this.q.includeEndpoints ? new Map() : undefined,
+                runtime: (0, bucket_metric_1.emptyRuntime)(),
+                flags: new Set(),
+                committedCount: 0,
+                uncommittedCount: 0
+            };
+            this.groups.set(key, g);
+        }
+        (0, bucket_metric_1.mergeInto)(g.requests, p.requests);
+        g.maxRps = Math.max(g.maxRps, bucketRps);
+        g.durationMs += b.durationMs;
+        g.bucketCount++;
+        if (committed === true)
+            g.committedCount++;
+        else if (committed === false)
+            g.uncommittedCount++;
+        if (b.startTime < g.startTime)
+            g.startTime = b.startTime;
+        if (b.endTime > g.endTime)
+            g.endTime = b.endTime;
+        g.sequenceFrom = Math.min(g.sequenceFrom, b.sequence);
+        const isLatest = b.sequence >= g.sequenceTo;
+        if (isLatest)
+            g.sequenceTo = b.sequence;
+        (0, bucket_metric_1.mergeRuntimeInto)(g.runtime, b.runtime, isLatest);
+        for (const f of b.qualityFlags)
+            g.flags.add(f);
+        if (g.endpoints) {
+            for (const e of p.endpoints) {
+                const ek = `${e.method}:${e.route}`;
+                let t = g.endpoints.get(ek);
+                if (!t) {
+                    t = { method: e.method, route: e.route, ...(0, bucket_metric_1.createAggregate)() };
+                    g.endpoints.set(ek, t);
+                }
+                (0, bucket_metric_1.mergeInto)(t, e);
+            }
+        }
+    }
+    finish() {
+        const points = [...this.groups.values()]
+            .sort((a, b) => (a.startTime < b.startTime ? -1 : a.startTime > b.startTime ? 1 : 0))
+            .map(g => ({
+            startTime: g.startTime,
+            endTime: g.endTime,
+            durationMs: g.durationMs,
+            bucketCount: g.bucketCount,
+            sequenceFrom: g.sequenceFrom,
+            sequenceTo: g.sequenceTo,
+            requests: g.requests,
+            maxRps: g.maxRps,
+            endpoints: g.endpoints ? [...g.endpoints.values()] : undefined,
+            runtime: g.runtime,
+            qualityFlags: [...g.flags].sort(),
+            committed: g.uncommittedCount > 0 ? false : g.committedCount === g.bucketCount ? true : null
+        }));
+        return {
+            query: this.q,
+            points,
+            total: {
+                requests: this.total,
+                durationMs: this.totalDurationMs,
+                bucketCount: this.bucketCount,
+                maxRps: this.maxRps,
+                derived: (0, bucket_metric_1.deriveMetrics)(this.total, this.totalDurationMs),
+            },
+            issues: this.issues,
+            complete: this.issues.length === 0,
+        };
+    }
+}
+class TelemetryQueryService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async query(q) {
+        const issues = [];
+        const acc = new SeriesAccumulator(q, issues);
+        for await (const e of this.buckets(q, i => issues.push(i)))
+            acc.add(e.bucket, e.committed);
+        return acc.finish();
+    }
+    recent(count, opts = {}) {
+        const consistency = opts.consistency ?? 'live';
+        const entries = this.deps.live.snapshot()
+            .filter(e => consistency === 'live' || e.committed)
+            .slice(-Math.max(0, count));
+        const first = entries[0]?.bucket;
+        const last = entries[entries.length - 1]?.bucket;
+        const now = new Date().toISOString();
+        const q = {
+            sessionId: this.deps.currentSessionId(),
+            from: first?.startTime ?? now,
+            to: last?.endTime ?? now,
+            consistency,
+            method: opts.method,
+            route: opts.route,
+            resolutionMs: opts.resolutionMs,
+            includeEndpoints: opts.includeEndpoints,
+        };
+        const acc = new SeriesAccumulator(q, []);
+        for (const e of entries)
+            acc.add(e.bucket, e.committed);
+        return acc.finish();
+    }
+    latestWindow(count, consistency) {
+        const entries = this.deps.live.snapshot()
+            .filter(e => consistency === 'live' || e.committed)
+            .slice(-Math.max(1, count));
+        if (entries.length === 0)
+            return null;
+        const first = entries[0].bucket;
+        const last = entries[entries.length - 1].bucket;
+        return {
+            sessionId: this.deps.currentSessionId(),
+            from: first.startTime,
+            to: last.endTime,
+            sequenceFrom: first.sequence,
+            sequenceTo: last.sequence,
+        };
+    }
+    liveBucket(sequence) {
+        return this.deps.live.snapshot().find(e => e.bucket.sequence === sequence)?.bucket;
+    }
+    async *buckets(q, onIssue) {
+        const { fromMs, toMs } = parseRange(q);
+        const isCurrent = q.sessionId === this.deps.currentSessionId();
+        const ramAll = isCurrent ? this.deps.live.snapshot() : [];
+        const ram = ramAll.filter(e => overlaps(e.bucket, fromMs, toMs) && (q.consistency === 'live' || e.committed));
+        const ramById = new Map(ram.map(e => [e.bucket.bucketId, e.bucket]));
+        const oldest = ramAll[0]?.bucket;
+        const covered = oldest !== undefined &&
+            (oldest.sequence === 1 || Date.parse(oldest.startTime) <= fromMs);
+        const handled = new Set();
+        if (!covered) {
+            try {
+                for await (const b of this.deps.committed.read(q.sessionId, fromMs, toMs, onIssue)) {
+                    const mem = ramById.get(b.bucketId);
+                    if (mem && fingerprint(mem) !== fingerprint(b)) {
+                        handled.add(b.bucketId);
+                        onIssue({ type: 'CONFLICT', bucketId: b.bucketId });
+                        continue;
+                    }
+                    handled.add(b.bucketId);
+                    yield { bucket: b, committed: true };
+                }
+            }
+            catch (err) {
+                onIssue({ type: 'SOURCE_ERROR', detail: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        for (const e of ram) {
+            if (handled.has(e.bucket.bucketId))
+                continue;
+            yield e;
+        }
+    }
+}
+exports.TelemetryQueryService = TelemetryQueryService;

package/dist/core/telemetry/telemetry.service.d.ts

@@ -1,10 +1,16 @@
 import type { TelemetryRequest } from '../domain';
-declare class TelemetryService {
+import type { ReadonlyConfig } from '../../config';
+export declare class TelemetryService {
     private readonly storage;
-    constructor(storage?: {
+    private readonly excludePatterns;
+    private inFlight;
+    private drainWaiters;
+    constructor(storage: {
         record(request: TelemetryRequest): void;
-    });
+    }, config: ReadonlyConfig);
     private isPathExcluded;
+    track(): () => void;
+    get inFlightCount(): number;
+    whenDrained(timeoutMs: number): Promise<boolean>;
     record(data: Omit<TelemetryRequest, 'timestamp' | 'responseTime'>, startHrTime: bigint): TelemetryRequest | null;
 }
-export default TelemetryService;