# `Dala.Event.Trace`
[🔗](https://github.com/manhvu/dala/blob/main/lib/dala/event/trace.ex#L1)

Live tracing of Dala events for IEx debugging.

Subscribe a process to receive every event that flows through `Dala.Event`.
Uses ETS for the registry; tracing is opt-in and adds zero cost when no
tracers are registered.

## Usage

    # In IEx connected to the running app:
    Dala.Event.Trace.start()
    Dala.Event.Trace.subscribe()

    # Now every event delivered via Dala.Event.dispatch/4 also lands in your
    # mailbox tagged {:dala_trace, addr, event, payload}. Pattern-match it,
    # log it, whatever.

    flush()  # see what's in the mailbox

    # Filter on the way out:
    Dala.Event.Trace.subscribe(fn addr -> addr.widget == :list end)

    # Stop tracing:
    Dala.Event.Trace.unsubscribe()
    Dala.Event.Trace.stop()

## Performance

When no tracers are registered (the default), `Dala.Event.dispatch/4` does
one ETS lookup: `:ets.whereis(:dala_event_trace)` returns `:undefined` and
the trace branch is a no-op. Cost ~50ns per dispatch.

When tracers are registered, each one is `send`ed a copy of the envelope.
Tracer filter functions run in the dispatch path, so keep them cheap.

# `broadcast`

```elixir
@spec broadcast(Dala.Event.Address.t(), atom(), term()) :: :ok
```

Called by `Dala.Event.dispatch/4` to deliver to all tracers. Internal API.

Only iterates if the table exists (cheap miss when tracing is disabled).

# `start`

```elixir
@spec start() :: :ok
```

Start the tracing table. Idempotent — safe to call multiple times.
Call once at app startup if you want tracing always available.

# `stop`

```elixir
@spec stop() :: :ok
```

Stop tracing and tear down the table.

# `subscribe`

```elixir
@spec subscribe((Dala.Event.Address.t() -> boolean()) | nil) :: :ok
```

Subscribe the current process to receive trace messages.

If `filter` is provided, only events for which `filter.(addr)` returns
truthy are delivered to this subscriber.

Messages arrive shaped `{:dala_trace, addr, event, payload}`.

# `unsubscribe`

```elixir
@spec unsubscribe() :: :ok
```

Unsubscribe the current process.

---

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