# Telemetry

The library emits `:telemetry` events for every Twilio API request, giving
you observability into latency, error rates, retry behavior, and more.

## Events

| Event | Measurements | Metadata |
|-------|-------------|----------|
| `[:twilio, :request, :start]` | `system_time` | `method`, `path`, `product` |
| `[:twilio, :request, :stop]` | `duration` | `method`, `path`, `product`, `status`, `retries`, `request_id`, `error` |
| `[:twilio, :request, :exception]` | `duration` | `method`, `path`, `product`, `kind`, `reason` |
| `[:twilio, :request, :retry]` | `attempt`, `wait_ms` | `method`, `path`, `product`, `status`, `reason` |

### Metadata Fields

| Field | Type | Description |
|-------|------|-------------|
| `method` | `atom` | HTTP method (`:get`, `:post`, `:delete`) |
| `path` | `String.t()` | Request path (e.g. `"/2010-04-01/Accounts/ACxxx/Messages.json"`) |
| `product` | `String.t()` | Twilio product domain (e.g. `"api"`, `"messaging"`, `"verify"`, `"conversations"`) |
| `status` | `integer \| nil` | HTTP status code (`nil` on connection errors) |
| `retries` | `integer` | Number of retries before final response (0 = first attempt succeeded) |
| `request_id` | `String.t() \| nil` | Twilio's server-side request ID from the `x-twilio-request-id` response header — useful for support tickets |
| `error` | `Twilio.Error.t() \| nil` | Error struct on failure, `nil` on success |
| `kind` | `atom` | Exception kind (`:error`, `:throw`, `:exit`) |
| `reason` | `term` | Exception reason or retry reason (`:rate_limited`, `:server_error`, `:connection_error`) |
| `attempt` | `integer` | Current retry attempt number |
| `wait_ms` | `integer` | Milliseconds to wait before retrying |

### Measurements

- `system_time` — wall-clock time at `:start` (from `System.system_time()`)
- `duration` — elapsed time in native units (use `System.convert_time_unit/3`)
- `attempt` — retry attempt counter (1 = first retry, 2 = second retry, etc.)
- `wait_ms` — backoff wait time in milliseconds

## Logging

Attach a handler to log every Twilio request:

```elixir
# lib/my_app/telemetry.ex
defmodule MyApp.Telemetry do
  require Logger

  def setup do
    :telemetry.attach_many("twilio-logger",
      [
        [:twilio, :request, :stop],
        [:twilio, :request, :exception],
        [:twilio, :request, :retry]
      ],
      &handle_event/4,
      nil
    )
  end

  defp handle_event([:twilio, :request, :stop], %{duration: duration}, meta, _config) do
    ms = System.convert_time_unit(duration, :native, :millisecond)
    retries = if meta.retries > 0, do: " (#{meta.retries} retries)", else: ""
    req_id = if meta.request_id, do: " [#{meta.request_id}]", else: ""

    if meta.error do
      Logger.error("Twilio #{meta.product} #{meta.method} #{meta.path} -> #{meta.status} in #{ms}ms#{retries}#{req_id}: #{meta.error.message}")
    else
      Logger.info("Twilio #{meta.product} #{meta.method} #{meta.path} -> #{meta.status} in #{ms}ms#{retries}#{req_id}")
    end
  end

  defp handle_event([:twilio, :request, :exception], %{duration: duration}, meta, _config) do
    ms = System.convert_time_unit(duration, :native, :millisecond)

    Logger.error("Twilio #{meta.product} #{meta.method} #{meta.path} raised #{inspect(meta.reason)} in #{ms}ms")
  end

  defp handle_event([:twilio, :request, :retry], %{attempt: attempt, wait_ms: wait}, meta, _config) do
    Logger.warning(
      "Twilio #{meta.product} #{meta.method} #{meta.path} retry ##{attempt} " <>
      "(#{meta.reason}, status: #{inspect(meta.status)}, waiting #{wait}ms)"
    )
  end
end
```

Call `MyApp.Telemetry.setup()` in your application's `start/2`:

```elixir
def start(_type, _args) do
  MyApp.Telemetry.setup()

  children = [
    # ...
  ]

  Supervisor.start_link(children, strategy: :one_for_one)
end
```

## StatsD / Prometheus

Route telemetry to your metrics backend:

```elixir
:telemetry.attach("twilio-metrics", [:twilio, :request, :stop], fn
  _event, %{duration: duration}, meta, _config ->
    ms = System.convert_time_unit(duration, :native, :millisecond)

    # Normalize high-cardinality path segments (SIDs)
    resource =
      meta.path
      |> String.split("/")
      |> Enum.map(fn seg ->
        if String.match?(seg, ~r/^(AC|SM|CA|MM|CF|PN|SK|US)[0-9a-f]{32}$/i) do
          ":sid"
        else
          seg
        end
      end)
      |> Enum.join("/")

    :telemetry.execute([:my_app, :twilio, :request], %{duration_ms: ms}, %{
      method: meta.method,
      product: meta.product,
      resource: resource,
      status: meta.status,
      retries: meta.retries,
      request_id: meta.request_id
    })
end, nil)
```

The SID pattern matching replaces 34-character Twilio SIDs (`SM` + 32 hex
chars) with `:sid` to keep metric cardinality low.

## Dashboard Queries

Common things to track:

- **P99 latency** by endpoint — group by `product` + `resource`, measure `duration_ms`
- **Error rate** — count events where `status >= 400` or `error != nil`
- **Retry rate** — count events where `retries > 0`
- **Rate limit hits** — count `:retry` events where `reason == :rate_limited`
- **Status code distribution** — group by `product` + `status`
- **Request tracing** — use `request_id` to correlate with Twilio support

## Retry Observability

The `:retry` event is emitted each time a request is retried, giving you
real-time visibility into retry behavior:

```
[warning] Twilio api POST /2010-04-01/.../Messages.json retry #1 (rate_limited, status: 429, waiting 1000ms)
[warning] Twilio api POST /2010-04-01/.../Messages.json retry #2 (rate_limited, status: 429, waiting 2340ms)
[info] Twilio api POST /2010-04-01/.../Messages.json -> 201 in 3456ms (2 retries) [RQxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx]
```

The `reason` field in retry metadata tells you why the retry happened:

| Reason | Trigger |
|--------|---------|
| `:rate_limited` | 429 response |
| `:server_error` | 500, 502, 503, or 409 response |
| `:connection_error` | `Mint.TransportError` (DNS, TLS, timeout) |

## Connection Pool Monitoring

The Finch connection pool also emits its own telemetry events. Attach to
`[:finch, :request, :stop]` for connection-level metrics, or
`[:finch, :queue, :stop]` for pool queue wait times.