feat: Add HTTP.Telemetry module to trace request and response.

Author: GSMLG-BOT

README.md

@@ -156,6 +156,39 @@ default_ua = HTTP.Headers.user_agent()
 {media_type, params} = HTTP.Headers.parse_content_type("application/json; charset=utf-8")
 ```
 
+### HTTP.Telemetry
+Comprehensive telemetry and metrics for HTTP requests and responses.
+
+```elixir
+# All HTTP.fetch operations automatically emit telemetry events
+# No configuration required - just attach handlers
+
+:telemetry.attach_many(
+  "my_handler",
+  [
+    [:http_fetch, :request, :start],
+    [:http_fetch, :request, :stop],
+    [:http_fetch, :request, :exception]
+  ],
+  fn event_name, measurements, metadata, _config ->
+    case event_name do
+      [:http_fetch, :request, :start] ->
+        IO.puts("Starting request to #{metadata.url}")
+      [:http_fetch, :request, :stop] ->
+        IO.puts("Request completed: #{measurements.status} in #{measurements.duration}μs")
+      [:http_fetch, :request, :exception] ->
+        IO.puts("Request failed: #{inspect(metadata.error)}")
+    end
+  end,
+  nil
+)
+
+# Manual telemetry events (for custom implementations)
+HTTP.Telemetry.request_start("GET", URI.parse("https://example.com"), %HTTP.Headers{})
+HTTP.Telemetry.request_stop(200, URI.parse("https://example.com"), 1024, 1500)
+HTTP.Telemetry.request_exception(URI.parse("https://example.com"), :timeout, 5000)
+```
+
 ### HTTP.Request
 Request configuration struct.
 

lib/http.ex

@@ -181,6 +181,9 @@ defmodule HTTP do
     # Extract AbortController PID from FetchOptions
     abort_controller_pid = options.signal
 
+    # Emit telemetry event for request start
+    HTTP.Telemetry.request_start(request.method, request.url, request.headers)
+
     # Spawn a task to handle the asynchronous HTTP request
     task =
       Task.Supervisor.async_nolink(
@@ -221,6 +224,8 @@ defmodule HTTP do
           pid() | nil
         ) :: Response.t() | {:error, term()}
   def handle_async_request(request, _calling_pid, abort_controller_pid) do
+    start_time = System.monotonic_time(:microsecond)
+
     # Use a try/catch block to convert `throw` from handle_httpc_response into an {:error, reason} tuple
     try do
       case Request.to_httpc_args(request) do
@@ -237,18 +242,46 @@ defmodule HTTP do
               end
 
               # Handle response (simplified - streaming handled in handle_httpc_response)
-              handle_response(request_id, request.url)
+              result = handle_response(request_id, request.url)
+
+              # Emit telemetry event for request completion
+              duration = System.monotonic_time(:microsecond) - start_time
+
+              case result do
+                %Response{status: status, body: body} when is_binary(body) ->
+                  HTTP.Telemetry.request_stop(status, request.url, byte_size(body), duration)
+
+                %Response{status: status, stream: nil} ->
+                  # Non-streaming response with nil body (unlikely, but handle)
+                  HTTP.Telemetry.request_stop(status, request.url, 0, duration)
+
+                %Response{status: status} ->
+                  # Streaming response - we'll emit telemetry when streaming completes
+                  HTTP.Telemetry.request_stop(status, request.url, 0, duration)
+
+                {:error, _} ->
+                  # Error will be handled in catch block
+                  :ok
+              end
+
+              result
 
             {:error, reason} ->
+              duration = System.monotonic_time(:microsecond) - start_time
+              HTTP.Telemetry.request_exception(request.url, reason, duration)
               throw(reason)
           end
 
         # Fallback for unexpected return from Request.to_httpc_args
         other_args ->
+          duration = System.monotonic_time(:microsecond) - start_time
+          HTTP.Telemetry.request_exception(request.url, {:bad_request_args, other_args}, duration)
           throw({:bad_request_args, other_args})
       end
     catch
       reason ->
+        duration = System.monotonic_time(:microsecond) - start_time
+        HTTP.Telemetry.request_exception(request.url, reason, duration)
         {:error, reason}
     end
   end
@@ -308,22 +341,33 @@ defmodule HTTP do
   defp should_use_streaming?(content_length) do
     # Stream responses larger than 5MB to avoid issues with large files
     case Integer.parse(content_length || "") do
-      {size, _} when size > 5_000_000 -> true
+      {size, _} when size > 5_000_000 ->
+        # Emit telemetry for streaming start
+        HTTP.Telemetry.streaming_start(size)
+        true
+
       # Stream when size is unknown
-      _ -> content_length == nil
+      _ ->
+        if content_length == nil do
+          HTTP.Telemetry.streaming_start(0)
+        end
+
+        content_length == nil
     end
   end
 
   defp start_httpc_stream_process(uri, headers) do
+    start_time = System.monotonic_time(:microsecond)
+
     {:ok, pid} =
       Task.start_link(fn ->
-        stream_httpc_response(uri, headers)
+        stream_httpc_response(uri, headers, start_time)
       end)
 
     {:ok, pid}
   end
 
-  defp stream_httpc_response(uri, headers) do
+  defp stream_httpc_response(uri, headers, start_time) do
     # Use the URI directly (it's already parsed)
     _host = uri.host
     _port = uri.port || 80
@@ -342,45 +386,62 @@ defmodule HTTP do
            sync: false
          ) do
       {:ok, request_id} ->
-        stream_loop(request_id, self())
+        stream_loop(request_id, self(), 0, start_time)
 
       {:error, reason} ->
         send(self(), {:stream_error, self(), reason})
     end
   end
 
-  defp stream_loop(request_id, caller) do
+  defp stream_loop(request_id, caller, total_bytes, start_time) do
     receive do
       {:http, {^request_id, {:http_response, _http_version, _status, _reason}}} ->
-        stream_loop(request_id, caller)
+        stream_loop(request_id, caller, total_bytes, start_time)
 
       {:http, {^request_id, {:http_header, _, _header_name, _, _header_value}}} ->
-        stream_loop(request_id, caller)
+        stream_loop(request_id, caller, total_bytes, start_time)
 
       {:http, {^request_id, :http_eoh}} ->
-        stream_loop(request_id, caller)
+        stream_loop(request_id, caller, total_bytes, start_time)
 
       {:http, {^request_id, {:http_error, reason}}} ->
         send(caller, {:stream_error, self(), reason})
 
       {:http, {^request_id, :stream_end}} ->
+        duration = System.monotonic_time(:microsecond) - start_time
+        HTTP.Telemetry.streaming_stop(total_bytes, duration)
         send(caller, {:stream_end, self()})
 
       {:http, {^request_id, {:http_chunk, chunk}}} ->
+        chunk_size = byte_size(chunk)
+        new_total = total_bytes + chunk_size
+        HTTP.Telemetry.streaming_chunk(chunk_size, new_total)
         send(caller, {:stream_chunk, self(), to_string(chunk)})
-        stream_loop(request_id, caller)
+        stream_loop(request_id, caller, new_total, start_time)
 
       {:http, {^request_id, {:http_body, body}}} ->
+        chunk_size = byte_size(body)
+        new_total = total_bytes + chunk_size
+        HTTP.Telemetry.streaming_chunk(chunk_size, new_total)
         send(caller, {:stream_chunk, self(), to_string(body)})
+        duration = System.monotonic_time(:microsecond) - start_time
+        HTTP.Telemetry.streaming_stop(new_total, duration)
         send(caller, {:stream_end, self()})
 
       {:http, {^request_id, {_status_line, _headers, body}}} ->
         # Handle complete response (non-streaming case)
         binary_body = if is_list(body), do: IO.iodata_to_binary(body), else: body
+        chunk_size = byte_size(binary_body)
+        new_total = total_bytes + chunk_size
+        HTTP.Telemetry.streaming_chunk(chunk_size, new_total)
         send(caller, {:stream_chunk, self(), binary_body})
+        duration = System.monotonic_time(:microsecond) - start_time
+        HTTP.Telemetry.streaming_stop(new_total, duration)
         send(caller, {:stream_end, self()})
     after
       60_000 ->
+        duration = System.monotonic_time(:microsecond) - start_time
+        HTTP.Telemetry.streaming_stop(total_bytes, duration)
         send(caller, {:stream_error, self(), :timeout})
     end
   end

lib/http/telemetry.ex

@@ -0,0 +1,131 @@
+defmodule HTTP.Telemetry do
+  @moduledoc """
+  Telemetry integration for HTTP fetch operations.
+
+  Provides event tracking and metrics collection for HTTP requests and responses.
+  """
+
+  @doc """
+  Emits a telemetry event for request start.
+
+  ## Examples
+      iex> HTTP.Telemetry.request_start("GET", URI.parse("https://example.com"), %HTTP.Headers{})
+      :ok
+  """
+  @spec request_start(String.t(), URI.t(), HTTP.Headers.t()) :: :ok
+  def request_start(method, url, headers) do
+    measurements = %{start_time: System.system_time(:millisecond)}
+
+    metadata = %{
+      method: method,
+      url: url,
+      headers: headers
+    }
+
+    :telemetry.execute([:http_fetch, :request, :start], measurements, metadata)
+  end
+
+  @doc """
+  Emits a telemetry event for request completion.
+
+  ## Examples
+      iex> HTTP.Telemetry.request_stop(200, URI.parse("https://example.com"), 1024, 1500)
+      :ok
+  """
+  @spec request_stop(integer(), URI.t(), integer(), integer()) :: :ok
+  def request_stop(status, url, response_size, duration_us) do
+    measurements = %{
+      duration: duration_us,
+      status: status,
+      response_size: response_size
+    }
+
+    metadata = %{url: url, status: status}
+
+    :telemetry.execute([:http_fetch, :request, :stop], measurements, metadata)
+  end
+
+  @doc """
+  Emits a telemetry event for request failure.
+
+  ## Examples
+      iex> HTTP.Telemetry.request_exception(URI.parse("https://example.com"), :timeout, 5000)
+      :ok
+  """
+  @spec request_exception(URI.t(), term(), integer()) :: :ok
+  def request_exception(url, error, duration_us) do
+    measurements = %{duration: duration_us}
+    metadata = %{url: url, error: error}
+
+    :telemetry.execute([:http_fetch, :request, :exception], measurements, metadata)
+  end
+
+  @doc """
+  Emits a telemetry event for response body reading start.
+
+  ## Examples
+      iex> HTTP.Telemetry.response_body_read_start(1024)
+      :ok
+  """
+  @spec response_body_read_start(integer()) :: :ok
+  def response_body_read_start(content_length) do
+    measurements = %{content_length: content_length}
+    :telemetry.execute([:http_fetch, :response, :body_read_start], measurements, %{})
+  end
+
+  @doc """
+  Emits a telemetry event for response body reading completion.
+
+  ## Examples
+      iex> HTTP.Telemetry.response_body_read_stop(1024, 500)
+      :ok
+  """
+  @spec response_body_read_stop(integer(), integer()) :: :ok
+  def response_body_read_stop(bytes_read, duration_us) do
+    measurements = %{bytes_read: bytes_read, duration: duration_us}
+    :telemetry.execute([:http_fetch, :response, :body_read_stop], measurements, %{})
+  end
+
+  @doc """
+  Emits a telemetry event for streaming start.
+
+  ## Examples
+      iex> HTTP.Telemetry.streaming_start(5242880)
+      :ok
+  """
+  @spec streaming_start(integer()) :: :ok
+  def streaming_start(content_length) do
+    measurements = %{content_length: content_length}
+    :telemetry.execute([:http_fetch, :streaming, :start], measurements, %{})
+  end
+
+  @doc """
+  Emits a telemetry event for streaming chunk received.
+
+  ## Examples
+      iex> HTTP.Telemetry.streaming_chunk(8192, 16384)
+      :ok
+  """
+  @spec streaming_chunk(integer(), integer()) :: :ok
+  def streaming_chunk(bytes_received, total_bytes) do
+    measurements = %{
+      bytes_received: bytes_received,
+      total_bytes: total_bytes
+    }
+
+    :telemetry.execute([:http_fetch, :streaming, :chunk], measurements, %{})
+  end
+
+  @doc """
+  Emits a telemetry event for streaming completion.
+
+  ## Examples
+      iex> HTTP.Telemetry.streaming_stop(5242880, 10000)
+      :ok
+  """
+  @spec streaming_stop(integer(), integer()) :: :ok
+  def streaming_stop(total_bytes, duration_us) do
+    measurements = %{total_bytes: total_bytes, duration: duration_us}
+    :telemetry.execute([:http_fetch, :streaming, :stop], measurements, %{})
+  end
+end

mix.lock

@@ -6,4 +6,5 @@
   "makeup_elixir": {:hex, :makeup_elixir, "1.0.1", "e928a4f984e795e41e3abd27bfc09f51db16ab8ba1aebdba2b3a575437efafc2", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "7284900d412a3e5cfd97fdaed4f5ed389b8f2b4cb49efc0eb3bd10e2febf9507"},
   "makeup_erlang": {:hex, :makeup_erlang, "1.0.2", "03e1804074b3aa64d5fad7aa64601ed0fb395337b982d9bcf04029d68d51b6a7", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "af33ff7ef368d5893e4a267933e7744e46ce3cf1f61e2dccf53a111ed3aa3727"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.4.2", "8efba0122db06df95bfaa78f791344a89352ba04baedd3849593bfce4d0dc1c6", [:mix], [], "hexpm", "4b21398942dda052b403bbe1da991ccd03a053668d147d53fb8c4e0efe09c973"},
+  "telemetry": {:hex, :telemetry, "1.3.0", "fedebbae410d715cf8e7062c96a1ef32ec22e764197f70cda73d82778d61e7a2", [:rebar3], [], "hexpm", "7015fc8919dbe63764f4b4b87a95b7c0996bd539e0d499be6ec9d7f3875b79e6"},
 }