# `Rheo.Telemetry`
[🔗](https://github.com/thanos/rheo/blob/v1.0.0/lib/rheo/telemetry.ex#L1)

Thin helpers around `:telemetry` for Rheo operations.

## Events

Backend spans (`:start` / `:stop` / `:exception` suffix, metadata `stream`
and, where relevant, `group`):

  * `[:rheo, :append]`, `[:rheo, :append_batch]`, `[:rheo, :query]`,
    `[:rheo, :fetch]`, `[:rheo, :lease, :renew]`, `[:rheo, :ack]`,
    `[:rheo, :retry]`, `[:rheo, :reject]`

Backend counters (`count` measurement):

  * `[:rheo, :stream, :create]`, `[:rheo, :group, :create]` — `stream`, `group`
  * `[:rheo, :lease]` — leases handed out by one fetch; `stream`, `group`, `consumer_id`
  * `[:rheo, :redelivery]`, `[:rheo, :dead_letter]` — `stream`, `group`, `event_id`
  * `[:rheo, :group, :frontier]`, `[:rheo, :group, :replay]`, `[:rheo, :group, :reset]`

Runtime (`Rheo.Group`, `Rheo.Producer`, `Rheo.Broadway.Acknowledger`):

  * `[:rheo, :consumer, :start | :stop]`, `[:rheo, :producer, :start | :stop]`
    — `stream`, `group`, `consumer_id`
  * `[:rheo, :fetch, :error]` — `stream`, `group`, `reason` (`Rheo.Settle`)
  * `[:rheo, :lease, :renew]` — `stream`, `group`, `event_id`, `result`
    (`:ok` or a `Rheo.Settle` reason)
  * `[:rheo, :ack | :retry | :reject, :error]` — `stream`, `group`,
    `event_id`, `reason` (`Rheo.Settle`)
  * `[:rheo, :handler, :error]` — a handler raised or threw; `event_id`, `reason`
  * `[:rheo, :worker, :crash]` — a handler task exited; `event_id`, `reason`
  * `[:rheo, :broadway, :ack | :retry | :reject]` — settled through the acknowledger

Metadata never includes event payloads. Attach handlers with
`:telemetry.attach/4` in your application.

# `execute`

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

Emits a telemetry event with measurements and metadata.

## Arguments

  * `event` — full event name, e.g. `[:rheo, :lease]`
  * `measurements` — map of numeric measurements
  * `metadata` — map of contextual metadata

## Examples

    iex> Rheo.Telemetry.execute([:rheo, :doctest_execute], %{count: 1}, %{stream: "demo"})
    :ok

## Returns

`:ok`

# `span`

```elixir
@spec span([atom()], map(), (-> result)) :: result when result: term()
```

Executes `fun` while emitting start/stop (or exception) telemetry events.

## Arguments

  * `event` — event name prefix as a list of atoms, e.g. `[:rheo, :append]`
  * `metadata` — map attached to all emissions
  * `fun` — zero-arity function to run

## Examples

    iex> Rheo.Telemetry.span([:rheo, :doctest_span], %{demo: true}, fn -> :ok end)
    :ok

## Returns

The return value of `fun`.

## Errors / raises

Re-raises any exception, throw, or exit from `fun` after emitting an
`:exception` event.

---

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