# `Insider.Recorder`
[🔗](https://github.com/hiivemarkets/insider/blob/v0.1.0/lib/insider/recorder.ex#L1)

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

# `drop_reason`

```elixir
@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
```

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `fill`

```elixir
@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`

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

# `handle`

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

# `read_since`

```elixir
@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`

```elixir
@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`

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

# `snapshot`

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

# `start_link`

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

# `status`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
