# `ExRatatui.Telemetry`
[🔗](https://github.com/mcass19/ex_ratatui/blob/v0.8.2/lib/ex_ratatui/telemetry.ex#L1)

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.

| Event | Description | Metadata |
| ----- | ----------- | -------- |
| `[: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

| Event | Description | Measurements | Metadata |
| ----- | ----------- | ------------ | -------- |
| `[: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.

# `attach_default_logger`

```elixir
@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`

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

Detaches the default logger previously attached with `attach_default_logger/1`.

# `execute`

```elixir
@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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*