fix(telemetry): evict buffered events only when that makes room (Q-6.9-11)

The buffer evicted lower-severity events one by one and only then found
the incoming event still did not fit, so both were lost (maxBytes 300,
info 50 + error 240, incoming warning 100: info evicted, warning
dropped). It now plans the evictions first (severity no higher than the
incoming one, lowest first, oldest first within a severity) and evicts
only if the plan frees enough room. The header comment now matches the
code: an event of the same severity is evicted, not only a lower one.

Verified: tests/platform/telemetry/telemetry-buffer.test.ts — the
review scenario RED before (info evicted), green after; same-severity
oldest-first eviction pinned. All gates PASS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:58:35 +09:00
co-authored by Claude Opus 5.5
parent 924ef3891c
commit b2f37f05b0
2 changed files with 64 additions and 28 deletions
+33 -28
View File
@@ -6,10 +6,11 @@ import {
/**
* Spec §25 / §27. Bounded, severity-aware telemetry buffer.
*
* The buffer never exceeds `maxEvents` or `maxBytes`. When full, the lowest
* severity (oldest first) event is evicted; an incoming event that is not more
* important than everything buffered is dropped instead. Buffer growth is
* never used as backpressure.
* The buffer never exceeds `maxEvents` or `maxBytes`. When full, buffered
* events no more severe than the incoming one are evicted, lowest severity
* first and oldest first within a severity, but only if that frees enough
* room; otherwise the incoming event is dropped and nothing is evicted.
* Buffer growth is never used as backpressure.
*/
export type BufferedTelemetryEvent = Readonly<{
event: TelemetryEvent<unknown>;
@@ -46,7 +47,7 @@ export function createTelemetryBuffer(
options: Readonly<{
maxEvents: number;
maxBytes: number;
/** Called for each buffered event evicted to make room for a more important one. */
/** Called for each buffered event evicted to make room for an incoming one. */
onEvict?: (entry: BufferedTelemetryEvent) => void;
}>,
): TelemetryBuffer {
@@ -61,19 +62,6 @@ export function createTelemetryBuffer(
let bytes = 0;
let dropped = 0;
function lowestIndex(): number {
let index = -1;
let rank = Number.POSITIVE_INFINITY;
for (let i = 0; i < entries.length; i += 1) {
const candidate = TELEMETRY_SEVERITY_RANK[(entries[i] as BufferedTelemetryEvent).event.severity];
if (candidate < rank) {
rank = candidate;
index = i;
}
}
return index;
}
return {
get size() {
return entries.length;
@@ -93,20 +81,37 @@ export function createTelemetryBuffer(
return false;
}
const incomingRank = TELEMETRY_SEVERITY_RANK[event.severity];
while (entries.length >= maxEvents || bytes + size > maxBytes) {
const victim = lowestIndex();
const victimEntry = entries[victim];
if (
!victimEntry ||
TELEMETRY_SEVERITY_RANK[victimEntry.event.severity] > incomingRank
) {
// Q-6.9-11. Plan the evictions before making any: an event is evicted
// only when the plan frees enough room for the incoming one.
const victims: BufferedTelemetryEvent[] = [];
let count = entries.length;
let used = bytes;
const full = () => count >= maxEvents || used + size > maxBytes;
if (full()) {
// Lowest severity first; the sort is stable, so oldest first within one.
const candidates = entries
.filter((entry) => TELEMETRY_SEVERITY_RANK[entry.event.severity] <= incomingRank)
.sort(
(a, b) =>
TELEMETRY_SEVERITY_RANK[a.event.severity] -
TELEMETRY_SEVERITY_RANK[b.event.severity],
);
for (const candidate of candidates) {
if (!full()) break;
victims.push(candidate);
count -= 1;
used -= candidate.bytes;
}
if (full()) {
dropped += 1;
return false;
}
entries.splice(victim, 1);
bytes -= victimEntry.bytes;
}
for (const victim of victims) {
entries.splice(entries.indexOf(victim), 1);
bytes -= victim.bytes;
dropped += 1;
onEvict?.(victimEntry);
onEvict?.(victim);
}
entries.push(
Object.freeze(
@@ -62,6 +62,37 @@ describe("createTelemetryBuffer", () => {
expect(buffer.dropped).toBe(1);
});
it("evicts nothing when eviction cannot make room for the incoming event (Q-6.9-11)", () => {
const at = (severity: TelemetryEvent<unknown>["severity"]) => ({
kind: `test.${severity}`,
severity,
});
const evicted: string[] = [];
const buffer = createTelemetryBuffer({
maxEvents: 10,
maxBytes: 300,
onEvict: (entry) => evicted.push(entry.event.severity),
});
buffer.push(at("info"), 50);
buffer.push(at("error"), 240);
// Dropping the info event frees 50 bytes; the warning needs 100.
expect(buffer.push(at("warning"), 100)).toBe(false);
expect(buffer.items.map((item) => item.severity)).toEqual(["info", "error"]);
expect(buffer.bytes).toBe(290);
expect(buffer.dropped).toBe(1);
expect(evicted).toEqual([]);
});
it("evicts the oldest event of the same severity to admit a new one", () => {
const buffer = createTelemetryBuffer({ maxEvents: 2, maxBytes: 1_024 });
buffer.push(infoEvent("a"));
buffer.push(infoEvent("b"));
expect(buffer.push(infoEvent("c"))).toBe(true);
expect(buffer.items).toEqual([infoEvent("b"), infoEvent("c")]);
expect(buffer.dropped).toBe(1);
});
it("enforces the byte ceiling independently of the event count", () => {
const buffer = createTelemetryBuffer({ maxEvents: 100, maxBytes: 200 });
for (let i = 0; i < 50; i += 1) buffer.push(infoEvent(`event-${i}`));