# `ExUnitJSON.Trace.Recorder`
[🔗](https://github.com/ZenHive/ex_unit_json/blob/main/lib/ex_unit_json/trace/recorder.ex#L1)

Per-test tracer process: the "flight recorder" half of message tracing.

Created by `ExUnitJSON.Trace` when a test opts in via `@tag trace_messages`.
The recorder owns an OTP-27 dynamic trace session (`:trace.session_create/3`)
with itself as the tracer, so it survives the test process dying on failure
(it is started *unlinked*). It records `:send`/`:receive` events of the traced
process tree into a bounded ring buffer, and when the monitored test process
exits it freezes the buffer, takes a best-effort mailbox snapshot of still-alive
traced processes, and writes the result to `ExUnitJSON.Trace.Store`.

Bounding is twofold: the ring keeps only the last `:cap` events, and a hard
`:budget` on total events received stops tracing entirely (setting `overflow`)
so a chatty process tree cannot flood the recorder's own mailbox.

# `event`

```elixir
@type event() :: map()
```

A recorded send/receive event with a relative microsecond timestamp

# `attach`

```elixir
@spec attach(pid(), [pid()], pid()) :: :ok
```

Begins tracing `trace_pids` and monitors `monitor_pid` (the test process).
Returns once tracing is active, so the caller's subsequent work is captured.

# `await`

```elixir
@spec await(pid()) :: :ok
```

Blocks until the recorder has written its buffer to the store, then stops it.

Called from an `on_exit` callback so the store write happens-before the formatter
reads it at `:test_finished`. The monitored process's `:DOWN` is already enqueued
by the time `on_exit` runs, so it is processed before this call — the snapshot is
taken while children are still alive. Tolerates an already-stopped recorder.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `start`

```elixir
@spec start(
  term(),
  keyword()
) :: {:ok, pid()}
```

Starts a recorder (unlinked, so it outlives the test process).

Options: `:cap` (ring size, default 50), `:budget` (max events
before tracing stops, default 5000).

---

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