Search documentation of mob

# Mob.Event.Trace (mob v0.6.18)

Copy Markdown View Source

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 `send`ed a copy of the envelope. Tracer filter functions run in the dispatch path, so keep them cheap.

## Summary

### Functions

broadcast(addr, event, payload)

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

start()

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

stop()

Stop tracing and tear down the table.

subscribe(filter \\ nil)

Subscribe the current process to receive trace messages.

unsubscribe()

Unsubscribe the current process.

## Functions

# broadcast(addr, event, payload)

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

# start()

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

    @spec stop() :: :ok

Stop tracing and tear down the table.

# subscribe(filter \\ nil)

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

# unsubscribe()

    @spec unsubscribe() :: :ok

Unsubscribe the current process.