Live tracing of Mob events for IEx debugging.
Subscribe a process to receive every event that flows through Mob.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:
Mob.Event.Trace.start()
Mob.Event.Trace.subscribe()
# Now every event delivered via Mob.Event.dispatch/4 also lands in your
# mailbox tagged {:mob_trace, addr, event, payload}. Pattern-match it,
# log it, whatever.
flush() # see what's in the mailbox
# Filter on the way out:
Mob.Event.Trace.subscribe(fn addr -> addr.widget == :list end)
# Stop tracing:
Mob.Event.Trace.unsubscribe()
Mob.Event.Trace.stop()Performance
When no tracers are registered (the default), Mob.Event.dispatch/4 does
one ETS lookup: :ets.whereis(:mob_event_trace) returns :undefined and
the trace branch is a no-op. Cost ~50ns per dispatch.
When tracers are registered, each one is sended a copy of the envelope.
Tracer filter functions run in the dispatch path, so keep them cheap.
Summary
Functions
Called by Mob.Event.dispatch/4 to deliver to all tracers. Internal API.
Start the tracing table. Idempotent — safe to call multiple times. Call once at app startup if you want tracing always available.
Stop tracing and tear down the table.
Subscribe the current process to receive trace messages.
Unsubscribe the current process.
Functions
@spec broadcast(Mob.Event.Address.t(), atom(), term()) :: :ok
Called by Mob.Event.dispatch/4 to deliver to all tracers. Internal API.
Only iterates if the table exists (cheap miss when tracing is disabled).
@spec start() :: :ok
Start the tracing table. Idempotent — safe to call multiple times. Call once at app startup if you want tracing always available.
@spec stop() :: :ok
Stop tracing and tear down the table.
@spec subscribe((Mob.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 {:mob_trace, addr, event, payload}.
@spec unsubscribe() :: :ok
Unsubscribe the current process.