# `Caracola.Telemetry`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/telemetry.ex#L1)

`:telemetry` events emitted by Caracola. They replace NkSIP's trace,
stats and debug facilities: attach handlers with `:telemetry.attach/4` to
log messages, collect metrics (for example with `Telemetry.Metrics`) or
trace calls.

All events carry the `:service` in their metadata.

## Messages

  * `[:caracola, :message, :received]` - a SIP message was received.
    Measurements: `:size` (bytes). Metadata: `:message`
    (`t:Caracola.Message.t/0`) and `:port` (`t:Caracola.Transport.Port.t/0`).
  * `[:caracola, :message, :sent]` - a SIP message (or keepalive) was
    sent. Measurements: `:size` (bytes). Metadata: `:message` (`nil` for
    raw data) and `:port`.

## Calls

  * `[:caracola, :call, :start]` - a call process (one per Call-ID) was
    started. Measurements: `:system_time` and `:monotonic_time`. Metadata:
    `:call_id`.
  * `[:caracola, :call, :stop]` - the call process finished. Measurements:
    `:duration` and `:monotonic_time`. Metadata: `:call_id`.

## Transactions

  * `[:caracola, :uac, :stop]` - a client transaction received its first
    final response. Measurements: `:duration` (since the request was
    created). Metadata: `:call_id`, `:method` and `:code`.
  * `[:caracola, :uas, :stop]` - a server transaction sent its first final
    response. Measurements: `:duration` (since the request was received).
    Metadata: `:call_id`, `:method` and `:code`.

## Dialogs

  * `[:caracola, :dialog, :start]` - a dialog was created. Measurements:
    `:system_time` and `:monotonic_time`. Metadata: `:call_id` and
    `:dialog_id`.
  * `[:caracola, :dialog, :stop]` - a dialog was removed. Measurements:
    `:duration` and `:monotonic_time`. Metadata: `:call_id` and
    `:dialog_id`.

## Plugins

  * `[:caracola, :rate_limit, :reject]` and `[:caracola, :rate_limit, :ban]` -
    see `Caracola.RateLimit`.
  * `[:caracola, :dispatcher, :status]` - see `Caracola.Dispatcher`.
  * `[:caracola, :overload_control, :drop]` - see `Caracola.OverloadControl`.

Durations are in `:native` time units, see `System.convert_time_unit/3`.

# `trace`

```elixir
@spec trace(boolean()) :: :ok
```

Logs every SIP message sent or received (with `Logger.info/2`), like
NkSIP's `nksip_trace`. `trace(false)` stops it.

---

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