LivePanels.Telemetry (livepanels v0.1.0)

Telemetry event helpers for LivePanels runtime observability.

LivePanels emits stable events around command application, shared session lifecycle, broadcast fanout, and layout persistence. Applications can attach handlers without LivePanels owning logging, metrics, or tracing policy.

The event catalog documents emitted measurements and metadata without putting catalog checks in the command and broadcast path.

Summary

Types

event_catalog_entry()

field_schema()

field_type()

Functions

broadcast_profile(state, payload_type, meta, profile)

Emits phase timings for shared-session broadcast work.

command_applied(state, meta)

Emits a successful canvas command event.

command_profile(state, meta, profile)

Emits phase timings for a canvas command.

command_rejected(state, meta)

Emits a rejected canvas command event.

delta_broadcast(state, meta)

Emits when a shared session broadcasts a versioned canvas delta.

events()

Returns the stable LivePanels telemetry event catalog.

item_broadcast(state, item_id, meta)

Emits when a shared session broadcasts a single item update.

layout_persisted(state)

Emits after a canvas layout is successfully persisted.

layout_persistence_failed(state, reason)

Emits after a canvas layout persistence attempt fails.

participant_joined(canvas_id, client_id, participant_count)

Emits when a shared-session participant joins.

participant_left(canvas_id, client_id, participant_count)

Emits when a shared-session participant leaves.

session_recovery(canvas_id, status, reason \\ nil)

Emits when shared-session recovery status changes.

session_started(canvas_id, opts)

Emits when a shared-session coordinator starts.

state_broadcast(state, meta)

Emits when a shared session broadcasts a full canvas state.

Types

event_catalog_entry()

@type event_catalog_entry() :: %{
  id: atom(),
  event: [atom()],
  measurements: %{required(atom()) => field_schema()},
  metadata: %{required(atom()) => field_schema()},
  description: String.t()
}

field_schema()

@type field_schema() :: %{type: field_type(), required?: boolean()}

field_type()

@type field_type() ::
  :atom
  | :boolean
  | :integer
  | :non_neg_integer
  | :string
  | :term
  | {:one_of, [atom()]}

Functions

broadcast_profile(state, payload_type, meta, profile)

@spec broadcast_profile(map(), :state | :item | :delta, map(), map()) :: :ok

Emits phase timings for shared-session broadcast work.

command_applied(state, meta)

@spec command_applied(map(), map()) :: :ok

Emits a successful canvas command event.

command_profile(state, meta, profile)

@spec command_profile(map(), map(), map()) :: :ok

Emits phase timings for a canvas command.

command_rejected(state, meta)

@spec command_rejected(map(), map()) :: :ok

Emits a rejected canvas command event.

delta_broadcast(state, meta)

@spec delta_broadcast(map(), map()) :: :ok

Emits when a shared session broadcasts a versioned canvas delta.

events()

@spec events() :: [event_catalog_entry()]

Returns the stable LivePanels telemetry event catalog.

The catalog names every event emitted by this module, along with the measurement and metadata keys applications can attach handlers around.

item_broadcast(state, item_id, meta)

@spec item_broadcast(map(), String.t(), map()) :: :ok

Emits when a shared session broadcasts a single item update.

layout_persisted(state)

@spec layout_persisted(map()) :: :ok

Emits after a canvas layout is successfully persisted.

layout_persistence_failed(state, reason)

@spec layout_persistence_failed(map(), term()) :: :ok

Emits after a canvas layout persistence attempt fails.

participant_joined(canvas_id, client_id, participant_count)

@spec participant_joined(String.t(), String.t(), non_neg_integer()) :: :ok

Emits when a shared-session participant joins.

participant_left(canvas_id, client_id, participant_count)

@spec participant_left(String.t(), String.t(), non_neg_integer()) :: :ok

Emits when a shared-session participant leaves.

session_recovery(canvas_id, status, reason \\ nil)

@spec session_recovery(String.t(), atom(), term()) :: :ok

Emits when shared-session recovery status changes.

session_started(canvas_id, opts)

@spec session_started(
  String.t(),
  keyword()
) :: :ok

Emits when a shared-session coordinator starts.

state_broadcast(state, meta)

@spec state_broadcast(map(), map()) :: :ok

Emits when a shared session broadcasts a full canvas state.