salt_edge_client

defmodule SaltEdgeClient.Telemetry do
  @moduledoc """
  Telemetry integration for the SaltEdge client.

  The client emits two events for every HTTP request:

  ## Events

  ### `[:salt_edge_client, :request, :start]`

  Emitted when a request is about to be dispatched.

  **Measurements:** `%{system_time: integer()}`

  **Metadata:** `%{method: atom(), path: String.t()}`

  ### `[:salt_edge_client, :request, :stop]`

  Emitted when a response (or error) is received.

  **Measurements:** `%{system_time: integer()}`

  **Metadata:** `%{method: atom(), path: String.t(), result: :ok | :error}`

  ## Attaching a handler

      :telemetry.attach_many(
        "saltedge-logger",
        [
          [:salt_edge_client, :request, :start],
          [:salt_edge_client, :request, :stop]
        ],
        &SaltEdgeClient.Telemetry.log/4,
        nil
      )

  ## Built-in logger handler

  `attach_default_logger/0` attaches a simple Logger-based handler:

      SaltEdgeClient.Telemetry.attach_default_logger()
  """

  require Logger

  @doc """
  Attaches a basic Logger handler for all SaltEdge telemetry events.

  Call this once during application startup, e.g. in `Application.start/2`.
  """
  @spec attach_default_logger() :: :ok | {:error, :already_exists}
  def attach_default_logger do
    :telemetry.attach_many(
      "saltedge-default-logger",
      [
        [:salt_edge_client, :request, :start],
        [:salt_edge_client, :request, :stop]
      ],
      &__MODULE__.log/4,
      nil
    )
  end

  @doc false
  def log([:salt_edge_client, :request, :start], _measurements, meta, _config) do
    Logger.debug("[SaltEdgeClient] → #{String.upcase(to_string(meta.method))} #{meta.path}")
  end

  def log([:salt_edge_client, :request, :stop], _measurements, %{result: :ok} = meta, _config) do
    Logger.debug("[SaltEdgeClient] ✓ #{String.upcase(to_string(meta.method))} #{meta.path}")
  end

  def log([:salt_edge_client, :request, :stop], _measurements, %{result: :error} = meta, _config) do
    Logger.warning("[SaltEdgeClient] ✗ #{String.upcase(to_string(meta.method))} #{meta.path}")
  end

  def log(_event, _measurements, _meta, _config), do: :ok

  @doc """
  Returns the list of telemetry event names emitted by this library.

  Useful for registration in telemetry supervisors (e.g. `telemetry_metrics`).
  """
  @type event_atom :: :salt_edge_client | :request | :start | :stop

  @spec events() :: nonempty_list(nonempty_list(event_atom()))
  def events do
    [
      [:salt_edge_client, :request, :start],
      [:salt_edge_client, :request, :stop]
    ]
  end
end