@origintrail-official/dkg-core 10.0.11 → 10.0.12

package/dist/backpressure-observability.d.ts

@@ -0,0 +1,175 @@
+export type BackpressureState = 'healthy' | 'degraded' | 'saturated' | 'stalled';
+export type SchedulerPressureOutcome = 'completed' | 'failed' | 'cancelled' | 'released';
+export interface SchedulerPressureCapacity {
+    queueLimit?: number | null;
+    inflightLimit?: number | null;
+    lanes?: Record<string, {
+        queueLimit?: number | null;
+        inflightLimit?: number | null;
+    }>;
+}
+export interface SchedulerPressureThresholds {
+    /** Queue age that turns otherwise-low utilization into degraded pressure. */
+    degradedQueueAgeMs?: number;
+    /** Active-work age that indicates an admitted operation may be stuck. */
+    stalledActiveAgeMs?: number;
+    /** Fraction of a bounded queue that marks a lane as degraded. */
+    degradedQueueUtilization?: number;
+    /** Keep a recent admission rejection visible as saturation for this long. */
+    rejectionStateWindowMs?: number;
+}
+export interface SchedulerPressureWork {
+    lane: string;
+    operation: string;
+}
+export interface SchedulerPressureTicket {
+    readonly id: number;
+}
+export interface BackpressureOperationSummary {
+    operation: string;
+    count: number;
+    oldestAgeMs: number;
+}
+export interface BackpressureLaneSnapshot {
+    lane: string;
+    state: BackpressureState;
+    queued: number;
+    queueLimit: number | null;
+    inflight: number;
+    inflightLimit: number | null;
+    oldestQueuedAgeMs: number;
+    oldestActiveAgeMs: number;
+    queuedOperations: BackpressureOperationSummary[];
+    activeOperations: BackpressureOperationSummary[];
+    events: Record<string, number>;
+    rejectedTotal: number;
+    rejectedByReason: Record<string, number>;
+    /** Age of the latest rejection; safe for monotonic or epoch-based clocks. */
+    lastRejectedAgeMs: number | null;
+}
+export interface BackpressureSnapshot {
+    scheduler: string;
+    state: BackpressureState;
+    totals: {
+        queued: number;
+        queueLimit: number | null;
+        inflight: number;
+        inflightLimit: number | null;
+        oldestQueuedAgeMs: number;
+        oldestActiveAgeMs: number;
+        rejectedTotal: number;
+    };
+    lanes: BackpressureLaneSnapshot[];
+}
+export interface BackpressureSource {
+    readonly backpressureId: string;
+    getBackpressureSnapshot(): BackpressureSnapshot;
+}
+export interface BackpressureRegistrySnapshot {
+    capturedAt: string;
+    state: BackpressureState;
+    schedulers: BackpressureSnapshot[];
+    failures: Array<{
+        scheduler: string;
+        error: string;
+    }>;
+}
+/**
+ * Keep metric/log dimensions bounded and strip payload-like punctuation.
+ * Callers should still pass static operation names rather than graph, peer, or
+ * job identifiers.
+ */
+export declare function normalizeBackpressureLabel(value: string, fallback?: string): string;
+export interface SchedulerPressureTrackerOptions {
+    scheduler: string;
+    capacity?: SchedulerPressureCapacity;
+    thresholds?: SchedulerPressureThresholds;
+    now?: () => number;
+}
+/**
+ * Scheduling-policy-neutral lifecycle tracker.
+ *
+ * Queue implementations call the five transition methods at their existing
+ * admission boundaries. The tracker owns timings, state classification,
+ * bounded metrics, and diagnostic snapshots, but never decides which work may
+ * run. All observability calls are fail-open so instrumentation cannot change
+ * scheduler behaviour.
+ */
+export declare class SchedulerPressureTracker {
+    readonly scheduler: string;
+    private readonly queued;
+    private readonly active;
+    private readonly lanes;
+    private readonly now;
+    private readonly thresholds;
+    private capacity;
+    private nextTicketId;
+    constructor(options: SchedulerPressureTrackerOptions);
+    updateCapacity(capacity: SchedulerPressureCapacity): void;
+    enqueue(work: SchedulerPressureWork): SchedulerPressureTicket;
+    start(ticket: SchedulerPressureTicket): void;
+    reject(work: SchedulerPressureWork, reason: string): void;
+    rejectQueued(ticket: SchedulerPressureTicket, reason: string): void;
+    cancelQueued(ticket: SchedulerPressureTicket, reason?: string): void;
+    finish(ticket: SchedulerPressureTicket, outcome: SchedulerPressureOutcome): void;
+    snapshot(): BackpressureSnapshot;
+    private runtimeFor;
+    private recordEvent;
+    private recordRejection;
+    private laneSnapshot;
+    private sumLaneLimits;
+    private safeMetric;
+}
+/**
+ * Base class for in-memory schedulers. Subclasses retain complete ownership of
+ * queue ordering, admission, coalescing, and release semantics and call these
+ * protected lifecycle methods at their existing boundaries.
+ */
+export declare abstract class ObservableScheduler implements BackpressureSource {
+    protected readonly pressure: SchedulerPressureTracker;
+    protected constructor(options: SchedulerPressureTrackerOptions);
+    get backpressureId(): string;
+    getBackpressureSnapshot(): BackpressureSnapshot;
+    protected updatePressureCapacity(capacity: SchedulerPressureCapacity): void;
+    protected pressureEnqueue(work: SchedulerPressureWork): SchedulerPressureTicket;
+    protected pressureStart(ticket: SchedulerPressureTicket): void;
+    protected pressureReject(work: SchedulerPressureWork, reason: string): void;
+    protected pressureRejectQueued(ticket: SchedulerPressureTicket, reason: string): void;
+    protected pressureCancelQueued(ticket: SchedulerPressureTicket, reason?: string): void;
+    protected pressureFinish(ticket: SchedulerPressureTicket, outcome: SchedulerPressureOutcome): void;
+}
+export declare class BackpressureRegistry {
+    private readonly sources;
+    register(source: BackpressureSource): () => void;
+    capture(): BackpressureRegistrySnapshot;
+}
+export declare const backpressureRegistry: BackpressureRegistry;
+export declare function recordBackpressureSnapshotMetrics(snapshot: BackpressureSnapshot): void;
+export interface BackpressureMonitorOptions {
+    registry?: BackpressureRegistry;
+    intervalMs?: number;
+    summaryIntervalMs?: number;
+    now?: () => number;
+    emit: (level: 'info' | 'warn', message: string, snapshot: BackpressureSnapshot, lane: BackpressureLaneSnapshot | null) => void;
+}
+/**
+ * One process-wide sampler provides transition/recovery logging and periodic
+ * summaries. It logs state changes rather than individual queue operations.
+ */
+export declare class BackpressureMonitor {
+    private readonly registry;
+    private readonly intervalMs;
+    private readonly summaryIntervalMs;
+    private readonly now;
+    private readonly emit;
+    private readonly logged;
+    private timer;
+    constructor(options: BackpressureMonitorOptions);
+    start(): void;
+    stop(): void;
+    sample(): void;
+    private observeSample;
+    private message;
+    private safeEmit;
+}
+//# sourceMappingURL=backpressure-observability.d.ts.map

package/dist/backpressure-observability.d.ts.map

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

package/dist/backpressure-observability.js

@@ -0,0 +1,495 @@
+import { getMetrics } from './telemetry-api.js';
+const DEFAULT_DEGRADED_QUEUE_AGE_MS = 5_000;
+const DEFAULT_STALLED_ACTIVE_AGE_MS = 30_000;
+const DEFAULT_DEGRADED_QUEUE_UTILIZATION = 0.75;
+const DEFAULT_REJECTION_STATE_WINDOW_MS = 60_000;
+const MAX_OPERATION_SUMMARIES = 8;
+const STATE_RANK = {
+    healthy: 0,
+    degraded: 1,
+    saturated: 2,
+    stalled: 3,
+};
+function maxState(a, b) {
+    return STATE_RANK[a] >= STATE_RANK[b] ? a : b;
+}
+function normalizeLimit(value) {
+    return Number.isFinite(value) && value >= 0 ? value : null;
+}
+/**
+ * Keep metric/log dimensions bounded and strip payload-like punctuation.
+ * Callers should still pass static operation names rather than graph, peer, or
+ * job identifiers.
+ */
+export function normalizeBackpressureLabel(value, fallback = 'unknown') {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return fallback;
+    return trimmed.replace(/[^\w:./-]/g, '_').slice(0, 80) || fallback;
+}
+function mapToRecord(map) {
+    return Object.fromEntries([...map.entries()].sort(([a], [b]) => a.localeCompare(b)));
+}
+function operationSummaries(records, timestamp, now) {
+    const byOperation = new Map();
+    for (const record of records) {
+        const existing = byOperation.get(record.operation);
+        const at = timestamp(record);
+        if (existing) {
+            existing.count += 1;
+            existing.oldestAt = Math.min(existing.oldestAt, at);
+        }
+        else {
+            byOperation.set(record.operation, { count: 1, oldestAt: at });
+        }
+    }
+    return [...byOperation.entries()]
+        .map(([operation, value]) => ({
+        operation,
+        count: value.count,
+        oldestAgeMs: Math.max(0, Math.floor(now - value.oldestAt)),
+    }))
+        .sort((a, b) => b.oldestAgeMs - a.oldestAgeMs || b.count - a.count || a.operation.localeCompare(b.operation))
+        .slice(0, MAX_OPERATION_SUMMARIES);
+}
+/**
+ * Scheduling-policy-neutral lifecycle tracker.
+ *
+ * Queue implementations call the five transition methods at their existing
+ * admission boundaries. The tracker owns timings, state classification,
+ * bounded metrics, and diagnostic snapshots, but never decides which work may
+ * run. All observability calls are fail-open so instrumentation cannot change
+ * scheduler behaviour.
+ */
+export class SchedulerPressureTracker {
+    scheduler;
+    queued = new Map();
+    active = new Map();
+    lanes = new Map();
+    now;
+    thresholds;
+    capacity;
+    nextTicketId = 1;
+    constructor(options) {
+        this.scheduler = normalizeBackpressureLabel(options.scheduler, 'scheduler');
+        this.capacity = options.capacity ?? {};
+        this.now = options.now ?? Date.now;
+        this.thresholds = {
+            degradedQueueAgeMs: options.thresholds?.degradedQueueAgeMs ?? DEFAULT_DEGRADED_QUEUE_AGE_MS,
+            stalledActiveAgeMs: options.thresholds?.stalledActiveAgeMs ?? DEFAULT_STALLED_ACTIVE_AGE_MS,
+            degradedQueueUtilization: options.thresholds?.degradedQueueUtilization ?? DEFAULT_DEGRADED_QUEUE_UTILIZATION,
+            rejectionStateWindowMs: options.thresholds?.rejectionStateWindowMs ?? DEFAULT_REJECTION_STATE_WINDOW_MS,
+        };
+    }
+    updateCapacity(capacity) {
+        this.capacity = capacity;
+    }
+    enqueue(work) {
+        const record = {
+            id: this.nextTicketId++,
+            lane: normalizeBackpressureLabel(work.lane, 'default'),
+            operation: normalizeBackpressureLabel(work.operation),
+            queuedAt: this.now(),
+        };
+        this.queued.set(record.id, record);
+        this.recordEvent(record.lane, 'enqueued');
+        return { id: record.id };
+    }
+    start(ticket) {
+        const record = this.queued.get(ticket.id);
+        if (!record)
+            return;
+        this.queued.delete(ticket.id);
+        record.startedAt = this.now();
+        this.active.set(ticket.id, record);
+        this.recordEvent(record.lane, 'started');
+        this.safeMetric(() => getMetrics().backpressureQueueWaitMs.record(Math.max(0, record.startedAt - record.queuedAt), { scheduler: this.scheduler, lane: record.lane }));
+    }
+    reject(work, reason) {
+        const lane = normalizeBackpressureLabel(work.lane, 'default');
+        this.recordRejection(lane, reason);
+    }
+    rejectQueued(ticket, reason) {
+        const record = this.queued.get(ticket.id);
+        if (!record)
+            return;
+        this.queued.delete(ticket.id);
+        this.recordRejection(record.lane, reason);
+    }
+    cancelQueued(ticket, reason = 'cancelled') {
+        const record = this.queued.get(ticket.id);
+        if (!record)
+            return;
+        this.queued.delete(ticket.id);
+        this.recordEvent(record.lane, 'cancelled', reason);
+    }
+    finish(ticket, outcome) {
+        const record = this.active.get(ticket.id);
+        if (!record)
+            return;
+        this.active.delete(ticket.id);
+        const finishedAt = this.now();
+        this.recordEvent(record.lane, outcome);
+        this.safeMetric(() => getMetrics().backpressureActiveDurationMs.record(Math.max(0, finishedAt - (record.startedAt ?? finishedAt)), {
+            scheduler: this.scheduler,
+            lane: record.lane,
+            outcome,
+        }));
+    }
+    snapshot() {
+        const now = this.now();
+        const laneNames = new Set([
+            ...this.lanes.keys(),
+            ...Object.keys(this.capacity.lanes ?? {}),
+            ...[...this.queued.values()].map((entry) => entry.lane),
+            ...[...this.active.values()].map((entry) => entry.lane),
+        ]);
+        const snapshots = [...laneNames]
+            .sort()
+            .map((lane) => this.laneSnapshot(lane, now));
+        const totals = {
+            queued: snapshots.reduce((sum, lane) => sum + lane.queued, 0),
+            queueLimit: normalizeLimit(this.capacity.queueLimit)
+                ?? this.sumLaneLimits('queueLimit', snapshots),
+            inflight: snapshots.reduce((sum, lane) => sum + lane.inflight, 0),
+            inflightLimit: normalizeLimit(this.capacity.inflightLimit)
+                ?? this.sumLaneLimits('inflightLimit', snapshots),
+            oldestQueuedAgeMs: Math.max(0, ...snapshots.map((lane) => lane.oldestQueuedAgeMs)),
+            oldestActiveAgeMs: Math.max(0, ...snapshots.map((lane) => lane.oldestActiveAgeMs)),
+            rejectedTotal: snapshots.reduce((sum, lane) => sum + lane.rejectedTotal, 0),
+        };
+        let state = snapshots.reduce((current, lane) => maxState(current, lane.state), 'healthy');
+        if (totals.queueLimit !== null
+            && totals.queueLimit > 0
+            && totals.queued >= totals.queueLimit) {
+            state = maxState(state, 'saturated');
+        }
+        else if (totals.queueLimit !== null
+            && totals.queueLimit > 0
+            && totals.queued / totals.queueLimit >= this.thresholds.degradedQueueUtilization) {
+            state = maxState(state, 'degraded');
+        }
+        if (totals.oldestQueuedAgeMs >= this.thresholds.degradedQueueAgeMs) {
+            state = maxState(state, 'degraded');
+        }
+        if (totals.oldestActiveAgeMs >= this.thresholds.stalledActiveAgeMs) {
+            state = maxState(state, 'stalled');
+        }
+        return {
+            scheduler: this.scheduler,
+            state,
+            totals,
+            lanes: snapshots,
+        };
+    }
+    runtimeFor(lane) {
+        let runtime = this.lanes.get(lane);
+        if (!runtime) {
+            runtime = {
+                events: new Map(),
+                rejectedByReason: new Map(),
+                lastRejectedAt: null,
+            };
+            this.lanes.set(lane, runtime);
+        }
+        return runtime;
+    }
+    recordEvent(lane, event, reason) {
+        const runtime = this.runtimeFor(lane);
+        runtime.events.set(event, (runtime.events.get(event) ?? 0) + 1);
+        this.safeMetric(() => getMetrics().backpressureEventsTotal.add(1, {
+            scheduler: this.scheduler,
+            lane,
+            event,
+            ...(reason ? { reason: normalizeBackpressureLabel(reason) } : {}),
+        }));
+    }
+    recordRejection(lane, reason) {
+        const normalizedReason = normalizeBackpressureLabel(reason, 'rejected');
+        const runtime = this.runtimeFor(lane);
+        runtime.rejectedByReason.set(normalizedReason, (runtime.rejectedByReason.get(normalizedReason) ?? 0) + 1);
+        runtime.lastRejectedAt = this.now();
+        this.recordEvent(lane, 'rejected', normalizedReason);
+    }
+    laneSnapshot(lane, now) {
+        const runtime = this.runtimeFor(lane);
+        const queued = [...this.queued.values()].filter((entry) => entry.lane === lane);
+        const active = [...this.active.values()].filter((entry) => entry.lane === lane);
+        const queueLimit = normalizeLimit(this.capacity.lanes?.[lane]?.queueLimit);
+        const inflightLimit = normalizeLimit(this.capacity.lanes?.[lane]?.inflightLimit);
+        const oldestQueuedAgeMs = queued.length === 0
+            ? 0
+            : Math.max(...queued.map((entry) => Math.max(0, Math.floor(now - entry.queuedAt))));
+        const oldestActiveAgeMs = active.length === 0
+            ? 0
+            : Math.max(...active.map((entry) => Math.max(0, Math.floor(now - (entry.startedAt ?? now)))));
+        let state = 'healthy';
+        if (oldestActiveAgeMs >= this.thresholds.stalledActiveAgeMs) {
+            state = 'stalled';
+        }
+        else if ((queueLimit !== null && queueLimit > 0 && queued.length >= queueLimit)
+            || (runtime.lastRejectedAt !== null
+                && now - runtime.lastRejectedAt <= this.thresholds.rejectionStateWindowMs)) {
+            state = 'saturated';
+        }
+        else if (oldestQueuedAgeMs >= this.thresholds.degradedQueueAgeMs
+            || (queueLimit !== null
+                && queueLimit > 0
+                && queued.length / queueLimit >= this.thresholds.degradedQueueUtilization)) {
+            state = 'degraded';
+        }
+        return {
+            lane,
+            state,
+            queued: queued.length,
+            queueLimit,
+            inflight: active.length,
+            inflightLimit,
+            oldestQueuedAgeMs,
+            oldestActiveAgeMs,
+            queuedOperations: operationSummaries(queued, (entry) => entry.queuedAt, now),
+            activeOperations: operationSummaries(active, (entry) => entry.startedAt ?? now, now),
+            events: mapToRecord(runtime.events),
+            rejectedTotal: [...runtime.rejectedByReason.values()].reduce((sum, value) => sum + value, 0),
+            rejectedByReason: mapToRecord(runtime.rejectedByReason),
+            lastRejectedAgeMs: runtime.lastRejectedAt === null
+                ? null
+                : Math.max(0, Math.floor(now - runtime.lastRejectedAt)),
+        };
+    }
+    sumLaneLimits(field, lanes) {
+        if (lanes.length === 0 || lanes.some((lane) => lane[field] === null))
+            return null;
+        return lanes.reduce((sum, lane) => sum + (lane[field] ?? 0), 0);
+    }
+    safeMetric(record) {
+        try {
+            record();
+        }
+        catch {
+            // Metrics are strictly fail-open.
+        }
+    }
+}
+/**
+ * Base class for in-memory schedulers. Subclasses retain complete ownership of
+ * queue ordering, admission, coalescing, and release semantics and call these
+ * protected lifecycle methods at their existing boundaries.
+ */
+export class ObservableScheduler {
+    pressure;
+    constructor(options) {
+        this.pressure = new SchedulerPressureTracker(options);
+    }
+    get backpressureId() {
+        return this.pressure.scheduler;
+    }
+    getBackpressureSnapshot() {
+        return this.pressure.snapshot();
+    }
+    updatePressureCapacity(capacity) {
+        this.pressure.updateCapacity(capacity);
+    }
+    pressureEnqueue(work) {
+        return this.pressure.enqueue(work);
+    }
+    pressureStart(ticket) {
+        this.pressure.start(ticket);
+    }
+    pressureReject(work, reason) {
+        this.pressure.reject(work, reason);
+    }
+    pressureRejectQueued(ticket, reason) {
+        this.pressure.rejectQueued(ticket, reason);
+    }
+    pressureCancelQueued(ticket, reason) {
+        this.pressure.cancelQueued(ticket, reason);
+    }
+    pressureFinish(ticket, outcome) {
+        this.pressure.finish(ticket, outcome);
+    }
+}
+export class BackpressureRegistry {
+    sources = new Map();
+    register(source) {
+        const id = normalizeBackpressureLabel(source.backpressureId, 'scheduler');
+        const existing = this.sources.get(id);
+        if (existing && existing !== source) {
+            throw new Error(`Backpressure source "${id}" is already registered`);
+        }
+        this.sources.set(id, source);
+        return () => {
+            if (this.sources.get(id) === source)
+                this.sources.delete(id);
+        };
+    }
+    capture() {
+        const schedulers = [];
+        const failures = [];
+        for (const [id, source] of [...this.sources.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+            try {
+                schedulers.push(source.getBackpressureSnapshot());
+            }
+            catch (error) {
+                failures.push({
+                    scheduler: id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return {
+            capturedAt: new Date().toISOString(),
+            state: schedulers.reduce((current, scheduler) => maxState(current, scheduler.state), 'healthy'),
+            schedulers,
+            failures,
+        };
+    }
+}
+export const backpressureRegistry = new BackpressureRegistry();
+export function recordBackpressureSnapshotMetrics(snapshot) {
+    const metrics = getMetrics();
+    const record = (lane, values) => {
+        const attributes = { scheduler: snapshot.scheduler, lane };
+        metrics.backpressureQueueDepth.record(values.queued, attributes);
+        metrics.backpressureInflight.record(values.inflight, attributes);
+        metrics.backpressureOldestQueuedAgeMs.record(values.oldestQueuedAgeMs, attributes);
+        metrics.backpressureOldestActiveAgeMs.record(values.oldestActiveAgeMs, attributes);
+        if (values.queueLimit !== null) {
+            metrics.backpressureQueueLimit.record(values.queueLimit, attributes);
+        }
+        if (values.inflightLimit !== null) {
+            metrics.backpressureInflightLimit.record(values.inflightLimit, attributes);
+        }
+    };
+    record('all', {
+        queued: snapshot.totals.queued,
+        queueLimit: snapshot.totals.queueLimit,
+        inflight: snapshot.totals.inflight,
+        inflightLimit: snapshot.totals.inflightLimit,
+        oldestQueuedAgeMs: snapshot.totals.oldestQueuedAgeMs,
+        oldestActiveAgeMs: snapshot.totals.oldestActiveAgeMs,
+    });
+    for (const lane of snapshot.lanes)
+        record(lane.lane, lane);
+}
+/**
+ * One process-wide sampler provides transition/recovery logging and periodic
+ * summaries. It logs state changes rather than individual queue operations.
+ */
+export class BackpressureMonitor {
+    registry;
+    intervalMs;
+    summaryIntervalMs;
+    now;
+    emit;
+    logged = new Map();
+    timer = null;
+    constructor(options) {
+        this.registry = options.registry ?? backpressureRegistry;
+        this.intervalMs = Math.max(1_000, options.intervalMs ?? 5_000);
+        this.summaryIntervalMs = Math.max(this.intervalMs, options.summaryIntervalMs ?? 60_000);
+        this.now = options.now ?? Date.now;
+        this.emit = options.emit;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.sample();
+        this.timer = setInterval(() => this.sample(), this.intervalMs);
+        if (typeof this.timer.unref === 'function')
+            this.timer.unref();
+    }
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    sample() {
+        const captured = this.registry.capture();
+        const now = this.now();
+        for (const scheduler of captured.schedulers) {
+            try {
+                recordBackpressureSnapshotMetrics(scheduler);
+            }
+            catch {
+                // The monitor must keep logging even if a metrics provider misbehaves.
+            }
+            const worstLaneState = scheduler.lanes.reduce((state, lane) => maxState(state, lane.state), 'healthy');
+            const samples = scheduler.lanes.map((lane) => ({
+                key: `${scheduler.scheduler}/${lane.lane}`,
+                state: lane.state,
+                lane,
+            }));
+            if (STATE_RANK[scheduler.state] > STATE_RANK[worstLaneState]) {
+                samples.push({
+                    key: `${scheduler.scheduler}/all`,
+                    state: scheduler.state,
+                    lane: null,
+                });
+            }
+            for (const sample of samples) {
+                this.observeSample(sample.key, sample.state, scheduler, sample.lane, now);
+            }
+        }
+    }
+    observeSample(key, state, scheduler, lane, now) {
+        const previous = this.logged.get(key);
+        if (state === 'healthy') {
+            if (previous && previous.state !== 'healthy') {
+                this.safeEmit('info', this.message('recovered', scheduler, lane, state, previous.state), scheduler, lane);
+            }
+            this.logged.set(key, { state, lastLoggedAt: previous?.lastLoggedAt ?? now });
+            return;
+        }
+        const transition = !previous || previous.state !== state;
+        const summaryDue = !previous || now - previous.lastLoggedAt >= this.summaryIntervalMs;
+        if (transition || summaryDue) {
+            this.safeEmit('warn', this.message(transition ? 'transition' : 'summary', scheduler, lane, state, previous?.state), scheduler, lane);
+            this.logged.set(key, { state, lastLoggedAt: now });
+        }
+    }
+    message(event, scheduler, lane, state, previousState) {
+        const values = lane ?? {
+            lane: 'all',
+            queued: scheduler.totals.queued,
+            queueLimit: scheduler.totals.queueLimit,
+            inflight: scheduler.totals.inflight,
+            inflightLimit: scheduler.totals.inflightLimit,
+            oldestQueuedAgeMs: scheduler.totals.oldestQueuedAgeMs,
+            oldestActiveAgeMs: scheduler.totals.oldestActiveAgeMs,
+            rejectedTotal: scheduler.totals.rejectedTotal,
+            queuedOperations: scheduler.lanes.flatMap((item) => item.queuedOperations)
+                .sort((a, b) => b.oldestAgeMs - a.oldestAgeMs)
+                .slice(0, MAX_OPERATION_SUMMARIES),
+            activeOperations: scheduler.lanes.flatMap((item) => item.activeOperations)
+                .sort((a, b) => b.oldestAgeMs - a.oldestAgeMs)
+                .slice(0, MAX_OPERATION_SUMMARIES),
+        };
+        return `[backpressure] ${JSON.stringify({
+            event,
+            scheduler: scheduler.scheduler,
+            lane: values.lane,
+            state,
+            ...(previousState ? { previousState } : {}),
+            queued: values.queued,
+            queueLimit: values.queueLimit,
+            inflight: values.inflight,
+            inflightLimit: values.inflightLimit,
+            oldestQueuedAgeMs: values.oldestQueuedAgeMs,
+            oldestActiveAgeMs: values.oldestActiveAgeMs,
+            rejectedTotal: values.rejectedTotal,
+            queuedOperations: values.queuedOperations,
+            activeOperations: values.activeOperations,
+        })}`;
+    }
+    safeEmit(level, message, scheduler, lane) {
+        try {
+            this.emit(level, message, scheduler, lane);
+        }
+        catch {
+            // Logging must never break scheduling or the monitor loop.
+        }
+    }
+}
+//# sourceMappingURL=backpressure-observability.js.map