Xqlite.Telemetry.Bridge (Xqlite v0.10.0)

Forwards multi-subscriber hook deliveries into :telemetry events.

This is the opt-in hook-bridge half of xqlite telemetry. The fan-out hooks (update, wal, commit, rollback, progress, plus the global log hook) deliver Erlang messages to subscribed pids. The bridge is a small GenServer that:

Subscribes to the requested hooks on a connection (or to the global log hook).
Receives each hook message in its mailbox.
Re-emits the message as a [:xqlite, :hook, :*] telemetry event.

Each bridge/2 (or bridge_log/1) call returns a struct holding the GenServer pid and the registered subscriber handles. Pass it to unbridge/1 to tear down all subscriptions and stop the GenServer.

Opt-in

Bridges are NEVER attached automatically. Users must call bridge/2 or bridge_log/1 explicitly for the connections / log hook they care about.

When telemetry is compile-disabled (config :xqlite, :telemetry_enabled, false, the default), bridge/2 and bridge_log/1 return {:error, :telemetry_disabled} rather than silently registering hooks that produce no events.

Per-connection bridge

{:ok, bridge} =
  Xqlite.Telemetry.bridge(conn,
    hooks: [:wal, :commit, :rollback, :update, :progress],
    tag: :replica_a
  )

# ... events fire as `[:xqlite, :hook, :wal]` etc ...

:ok = Xqlite.Telemetry.unbridge(bridge)

Global log bridge

{:ok, log_bridge} = Xqlite.Telemetry.bridge_log()
:ok = Xqlite.Telemetry.unbridge(log_bridge)

Busy events

Busy observation is multi-subscriber (Xqlite.register_busy_observer/2) and included in the bridge: pass hooks: [:busy] (or the default :all) and every contention callback re-emits as [:xqlite, :hook, :busy]. The retry POLICY half (Xqlite.set_busy_policy/2) stays single-slot — a retry decision cannot compose — and is independent of observation.

Summary

Types

hook_kind()

scope()

t()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.