urp

defmodule URP.Telemetry do
  @moduledoc """
  Telemetry events emitted by URP.

  ## Events

  ### `[:urp, :call, :stop]`

  Emitted after every pool checkout completes (all operations go through
  `URP.Pool.do_checkout/5`).

  #### Measurements (in `:native` time units)

  | Key | Description |
  |---|---|
  | `:total_time` | Wall time from checkout request to work completion |
  | `:queue_time` | Time spent waiting for a pool connection |
  | `:service_time` | Time spent doing work on the connection |

  Use `System.convert_time_unit/3` to convert to milliseconds or
  microseconds:

      System.convert_time_unit(queue_time, :native, :millisecond)

  #### Metadata

  | Key | Type | Description |
  |---|---|---|
  | `:operation` | `atom` | The operation performed (e.g. `:convert`, `:version`, `:filters`) |
  | `:pool` | `term` | The pool name or pid |
  | `:result` | `:ok \\| :error` | Whether the operation succeeded |

  ## Example handler

      :telemetry.attach(
        "urp-logger",
        [:urp, :call, :stop],
        fn event, measurements, metadata, _config ->
          total_ms = System.convert_time_unit(measurements.total_time, :native, :millisecond)
          queue_ms = System.convert_time_unit(measurements.queue_time, :native, :millisecond)

          Logger.info(
            "[URP] \#{metadata.operation} \#{metadata.result} " <>
              "total=\#{total_ms}ms queue=\#{queue_ms}ms"
          )
        end,
        nil
      )
  """
end