asobi_script_log_limiter (asobi v0.72.5)

View Source

Bounds the rate of log lines emitted from per-tick, script-driven error paths - a game script that fails on every tick (a typo'd spawn template, a Lua callback that always raises) would otherwise log once per tick forever (asobi#252). Telemetry counters are unaffected: asobi_telemetry:game_error/2 is cheap to aggregate at any volume and callers should keep emitting it unconditionally so dashboards/alerts see the true failure rate. Only the disk/log-aggregator cost of the structured log line itself is bounded here.

Backed by the existing seki limiter (asobi_script_log_limiter, registered in asobi_sup), keyed per call site by whatever the caller considers "the same recurring failure" - typically {WorldId, Coords} for a zone or {Script, Callback} for a Lua callback. Suppressed calls are not silently dropped: allow/1 returns how many were suppressed since the last allowed call, so the next log line that does get through can say "and N more like this were suppressed" instead of the gap just looking like the failure stopped.

Summary

Functions

Check whether a log line for Key is allowed right now.

Drop any pending drop-count row for Key. Callers whose Key's lifetime is bounded (e.g. a zone process, keyed on {WorldId, Coords}) should call this when that lifetime ends, so a Key that suppressed a log line right before terminating doesn't leave a permanent stale row behind.

Create the drop-count table once at boot (asobi_sup); idempotent.

Functions

allow(Key)

-spec allow(term()) -> {true, non_neg_integer()} | false.

Check whether a log line for Key is allowed right now.

Returns {true, PreviouslyDropped} when the caller should log - PreviouslyDropped is the count of calls suppressed for this Key since the last time allow/1 returned true (0 the first time / when nothing was suppressed). Returns false when the caller should skip logging this occurrence (the drop is still counted for the next allowed call to report).

forget(Key)

-spec forget(term()) -> ok.

Drop any pending drop-count row for Key. Callers whose Key's lifetime is bounded (e.g. a zone process, keyed on {WorldId, Coords}) should call this when that lifetime ends, so a Key that suppressed a log line right before terminating doesn't leave a permanent stale row behind.

init_table()

-spec init_table() -> ok.

Create the drop-count table once at boot (asobi_sup); idempotent.