Insider.Recorder (Insider v0.1.0)

Copy Markdown View Source

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

drop_reason()

@type drop_reason() ::
  :invalid_event
  | :classification_failed
  | :contended
  | :rate_limited
  | :rate_key_capacity
  | :oversized
  | :frozen
  | :event_id_conflict
  | :priority_protected
  | :eviction_limit
  | :unavailable
  | :internal_error

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

fill(handle)

@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.

freeze(handle, trigger_event)

@spec freeze(Insider.Recorder.Handle.t(), term()) ::
  {:ok, String.t()} | {:error, :already_frozen | :busy | drop_reason()}

handle(server)

@spec handle(GenServer.server()) ::
  {:ok, Insider.Recorder.Handle.t()} | {:error, :unavailable}

read_since(handle, cursor, options \\ [])

@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).

receipt(handle, event_id)

@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.

record(handle, event)

@spec record(Insider.Recorder.Handle.t(), term()) :: :ok | {:dropped, drop_reason()}

snapshot(handle)

@spec snapshot(Insider.Recorder.Handle.t()) ::
  {:ok, Insider.Recorder.Snapshot.t()}
  | {:pending, map()}
  | {:error, :not_triggered | :busy | :unavailable}

start_link(options \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

status(handle)

@spec status(Insider.Recorder.Handle.t()) ::
  {:ok, map()} | {:error, :busy | :unavailable}