Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
/** Distinct keys one throttle tracks before new keys share a single entry. */
export const LOG_THROTTLE_MAX_KEYS = 1_000
/**
* Bounds how many lines one event writes: at most one per key per interval.
* A suppressed event is only counted, and the next admitted line for that key
* carries the count, so no occurrence disappears from the log without a trace.
* Callers keep their metrics unthrottled; this only sheds log volume, such as
* one warn line per request while the rate-limit backend is down.
*
* Keys idle for two intervals are dropped by a sweep that runs at most once per
* interval, so the map is bounded by the keys active in the last two intervals.
* A count still pending when its key is swept is lost from the log, not from
* the metrics.
*
* Keys often come from clients, and a client can send a new one on every
* request. Once `maxKeys` keys are tracked, every key not already tracked shares
* one overflow entry: together they get at most one line per interval, and that
* line carries their combined suppressed count. So one interval writes at most
* `maxKeys + 1` lines, and the map holds at most `maxKeys + 1` entries.
*/
export class LogThrottle {
private readonly entries = new Map<string, { emittedAt: number; suppressed: number }>()
private lastSweep: number
constructor(
private readonly intervalMs: number,
private readonly now: () => number = () => Date.now(),
private readonly maxKeys: number = LOG_THROTTLE_MAX_KEYS
) {
if (!(intervalMs > 0)) throw new Error('LogThrottle: intervalMs must be > 0')
if (!Number.isSafeInteger(maxKeys) || maxKeys < 1) {
throw new Error('LogThrottle: maxKeys must be a positive integer')
}
this.lastSweep = now()
}
/** Number of keys currently held. Read by tests to observe the sweep. */
get trackedKeyCount(): number {
return this.entries.size
}
/**
* Record one event for `key`. Returns the number of events suppressed since
* the key's previous line when a line is due now, or `undefined` when this
* event is suppressed.
*/
admit(key: string): number | undefined {
const now = this.now()
this.sweep(now)
const trackedKey =
this.entries.has(key) || this.entries.size < this.maxKeys ? key : OVERFLOW_KEY
const entry = this.entries.get(trackedKey)
if (entry && now - entry.emittedAt < this.intervalMs) {
entry.suppressed += 1
return undefined
}
this.entries.set(trackedKey, { emittedAt: now, suppressed: 0 })
return entry?.suppressed ?? 0
}
private sweep(now: number): void {
if (now - this.lastSweep < this.intervalMs) return
for (const [key, entry] of this.entries) {
if (now - entry.emittedAt >= 2 * this.intervalMs) this.entries.delete(key)
}
this.lastSweep = now
}
}
// A NUL byte cannot appear in a key built from a header, a URL or a hex hash,
// so the overflow entry cannot collide with a real key.
const OVERFLOW_KEY = '\u0000overflow'