A bounded, non-mailbox flight recorder for normalized events.
Hot-path writes go directly through a recorder-owned bounded ETS store,
never through a recorder mailbox. Admission is a short ticket lock:
writers are admitted one at a time in the order they arrived, and a
writer that finds the lock held waits for its turn rather than dropping
its event. A holder or waiter that died is passed over. A writer gives up
with :contended only when the lock has not changed hands for
admission_stall_ms (default 1,000); that and every other loss is
returned and counted.
Precondition: call record/2, freeze/2, status/1, and snapshot/1
from Insider-owned collector or control processes, never from an
application process. A call may wait while other writers are admitted,
for as long as the lock keeps changing hands. Insider's collectors meet
that precondition: Logger and Telemetry handlers run in the emitting
process but only write to their collector's bounded inbox, and the
collector process records. A collector held up by a stuck holder backs up
into that inbox, which sheds with counted loss.
Source shares. Each event source has a reserved share of the event
and byte bounds (Insider.Recorder.Config). When a write needs room, a
source over its share evicts its own oldest entries first; a source within
its share takes the oldest entries of sources over theirs. A normal write
never evicts another source's entries while that source is within its
share in both events and bytes, so one noisy source cannot evict the
others' evidence. Protected entries keep their precedence: a normal write
never evicts them, and a protected write may evict any normal entry and
then other protected entries (never the freeze trigger), each time taking
its own source's and over-share sources' entries before the rest.
Evictions are counted per source in fill/1 and status/1.
Summary
Functions
Returns a specification to start this module under a supervisor.
How full the recorder is, read without the admission lock so it never
delays a concurrent producer: the newest receipt assigned
(next_receipt, 0 before the first), the oldest retained receipt (nil
when nothing is retained), the retained event count and stored bytes with
the bounds they are held to, sources (each share group's
share_percent, reserved_events, reserved_bytes, retained_events,
retained_bytes, and the entries it has had evicted; sources without a
share of their own are the "other" group), and memory_bytes: the
Recorder's tables and the canonical event binaries they hold off heap.
Reads retained entries whose receipt is greater than cursor, in receipt
order, without requiring a freeze trigger.
The receipt of the retained event with id event_id, or nil when it was
never admitted or is no longer retained. A collector that records an
event and must name it elsewhere (a summary's exemplar) reads it here.
Types
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec fill(Insider.Recorder.Handle.t()) :: {:ok, map()} | {:error, :unavailable}
How full the recorder is, read without the admission lock so it never
delays a concurrent producer: the newest receipt assigned
(next_receipt, 0 before the first), the oldest retained receipt (nil
when nothing is retained), the retained event count and stored bytes with
the bounds they are held to, sources (each share group's
share_percent, reserved_events, reserved_bytes, retained_events,
retained_bytes, and the entries it has had evicted; sources without a
share of their own are the "other" group), and memory_bytes: the
Recorder's tables and the canonical event binaries they hold off heap.
The per-source evicted counts and the cumulative evicted counter of
status/1, their sum, are conservative: an eviction is counted before its
entry is deleted, so a writer killed in between leaves a counted entry
still retained (counted again if it is evicted later). They never
undercount. The receipt-range evicted of read_since/3 is exact.
@spec freeze(Insider.Recorder.Handle.t(), term()) :: {:ok, String.t()} | {:error, :already_frozen | :busy | drop_reason()}
@spec handle(GenServer.server()) :: {:ok, Insider.Recorder.Handle.t()} | {:error, :unavailable}
@spec read_since(Insider.Recorder.Handle.t(), non_neg_integer() | :latest, keyword()) :: {:ok, map()} | {:error, :invalid_cursor | :invalid_options | :unavailable}
Reads retained entries whose receipt is greater than cursor, in receipt
order, without requiring a freeze trigger.
Receipts are assigned consecutively on admission, so every receipt in
cursor < receipt <= next_cursor that is not returned was evicted; the
result reports that exact count as evicted. Admission losses never receive
a receipt and are visible only in the returned cumulative counters.
The read takes no admission lock, so it never delays a concurrent
producer. It observes the highest receipt assigned when the
read began; later admissions are left for the next read. Cursor :latest
is that highest receipt, so the read returns nothing and starts a tail.
limit (1..1,000, default 100) bounds entries and max_bytes (1..16 MiB,
default 1 MiB) bounds stored entry bytes, except that one available entry
is always returned so a reader makes progress. truncated reports either
bound and truncated_by names it (:limit or :max_bytes, else nil).
@spec receipt(Insider.Recorder.Handle.t(), String.t()) :: pos_integer() | nil
The receipt of the retained event with id event_id, or nil when it was
never admitted or is no longer retained. A collector that records an
event and must name it elsewhere (a summary's exemplar) reads it here.
@spec record(Insider.Recorder.Handle.t(), term()) :: :ok | {:dropped, drop_reason()}
@spec snapshot(Insider.Recorder.Handle.t()) :: {:ok, Insider.Recorder.Snapshot.t()} | {:pending, map()} | {:error, :not_triggered | :busy | :unavailable}
@spec start_link(keyword()) :: GenServer.on_start()
@spec status(Insider.Recorder.Handle.t()) :: {:ok, map()} | {:error, :busy | :unavailable}