Depot.Telemetry

Depot.Telemetry: query-level observability hooks.

A thin callback registry for observing every SQL query that passes through Depot. Callers register a handler with attach(name, fn); every subsequent query emits a QueryEvent to every registered handler. Handlers are invoked inside __try_call_val, so a panicking handler is isolated — other handlers still fire and the calling query is unaffected.

Handlers are stored in a named Vault table (__depot_telemetry__) so registration is process-global and survives across modules. The registry key is the user-supplied handler name (a String); re-using a name overwrites the previous handler.

Usage:

Depot.Telemetry.attach("stdout", fn ev ->
  IO.println(ev.sql ++ " (" ++ int_to_string(ev.duration_ms) ++ "ms)")
end)

-- ... later, inside a query-issuing function ...
Depot.Telemetry.instrument(sql, params, fn _ ->
  Connection.exec_prepared(conn, sql, params)
)

Depot.Telemetry.detach("stdout")

Types

typeQueryEventFieldsQueryEventFields = {#

typeQueryEventQueryEvent = QueryEvent(QueryEventFields)#

Functions

fnattachattach(name, handler)#

Attach a handler to query events. name identifies the handler for later detach; re-attaching with the same name overwrites.

  Depot.Telemetry.attach("log", fn ev -> IO.println(ev.sql) end)

fnclearclear()#

Remove all handlers. Primarily useful for test isolation.

fndetachdetach(name)#

Remove a handler by name. No-op if the name is not registered.

fnemitemit(event)#

Emit a QueryEvent to every registered handler.

Each handler runs inside __try_call_val; if one raises, the event is still delivered to the remaining handlers and emit itself never raises.

fnevent_ofevent_of(sql, params, duration_ms, result)#

fnhandler_nameshandler_names()#

Return the list of currently registered handler names.

fninstrumentinstrument(sql, params, thunk)#

Wrap a query-running thunk with timing + event emission.

Calls thunk(), measures wall-clock duration via System.monotonic_time, builds a QueryEvent from the result shape, emits it, and returns the original result unchanged.

  Depot.Telemetry.instrument(sql, params, fn _ ->
    Db.exec(conn, sql, params)
  )