ExRatatui.Telemetry (ExRatatui v0.8.2)

Copy Markdown View Source

Telemetry integration for ExRatatui.

ExRatatui emits :telemetry events so applications can plug in logging, metrics, and distributed tracing without forking the runtime. The API follows the conventions: every long-running operation is wrapped in a span, every one-off operation is a single execute, and every event carries a stable metadata shape you can match on.

Events

All events are prefixed with :ex_ratatui.

Span events (:start / :stop / :exception)

Each span emits three events with the suffix appended to the event name. Handlers typically attach to :stop for timing and :exception for failure tracking.

EventDescriptionMetadata
[:ex_ratatui, :runtime, :init]App mount callback (mount/1).:mod, :transport
[:ex_ratatui, :runtime, :event]Terminal event decode + user handle_event/2 dispatch.:mod, :transport, :event
[:ex_ratatui, :runtime, :update]Info-message dispatch (subscriptions, async results, user handle_info/2).:mod, :transport, :msg
[:ex_ratatui, :render, :frame]Frame build + draw cycle.:mod, :transport, :widget_count
[:ex_ratatui, :transport, :connect]Transport wiring for a session (terminal init, SSH session bind, distributed client monitor).:mod, :transport

:start events carry %{monotonic_time: integer, system_time: integer} as measurements. :stop events add :duration (native units). On exception the metadata gains :kind, :reason, and :stacktrace.

Single events

EventDescriptionMeasurementsMetadata
[:ex_ratatui, :session, :lifecycle, :open]A session-backed runtime adopted a session.%{system_time: integer}:mod, :transport, :width, :height
[:ex_ratatui, :session, :lifecycle, :close]A session-backed runtime released its session. Fires exactly once per session even when transport-level cleanup also closes the session ref.%{system_time: integer}:mod, :transport, :reason
[:ex_ratatui, :render, :dropped]A frame was skipped (draw error or future backpressure).%{system_time: integer}:mod, :transport, :reason
[:ex_ratatui, :transport, :disconnect]Session tore down.%{system_time: integer}:mod, :transport, :reason

Attaching a default logger

# in your Application.start/2 or iex
ExRatatui.Telemetry.attach_default_logger()

That attaches a handler that logs every :stop and single event at :debug level. Pass a custom level with attach_default_logger(level: :info).

See guides/telemetry.md for a full wiring example with Telemetry.Metrics or OpenTelemetry.

Summary

Functions

attach_default_logger(opts \\ [])

Attaches a logger that prints every ExRatatui telemetry event.

detach_default_logger()

Detaches the default logger previously attached with attach_default_logger/1.

execute(event, measurements, meta)

Emits a single :telemetry event rooted at [:ex_ratatui | event].

span(event, meta, fun)

Wraps fun in a :telemetry span rooted at [:ex_ratatui | event].

Functions

attach_default_logger(opts \\ [])

@spec attach_default_logger(keyword()) :: :ok | {:error, :already_exists}

Attaches a logger that prints every ExRatatui telemetry event.

Useful during development. Detach with detach_default_logger/0.

Options

  • :level — log level (default: :debug).
  • :events — list of event suffixes to attach (default: all).

detach_default_logger()

@spec detach_default_logger() :: :ok | {:error, :not_found}

Detaches the default logger previously attached with attach_default_logger/1.

execute(event, measurements, meta)

@spec execute([atom(), ...], map(), map()) :: :ok

Emits a single :telemetry event rooted at [:ex_ratatui | event].

:system_time is added to the measurements automatically if not already present.

span(event, meta, fun)

@spec span([atom(), ...], map(), (-> term())) :: term()

Wraps fun in a :telemetry span rooted at [:ex_ratatui | event].

The fun's return value is returned unchanged. The given meta is forwarded to both the :start and :stop events (plus the standard :telemetry_span_context). If you need extra metadata on :stop specifically, call :telemetry.span/3 directly.