Telemetry integration for comprehensive HTTP request and response monitoring.

This module provides automatic telemetry event emission for all HTTP operations, enabling observability, metrics collection, and performance monitoring. All events use the [:http_fetch, ...] prefix.

Automatic Events

All HTTP.fetch/2 operations automatically emit telemetry events. No configuration is required - simply attach handlers to receive events.

Event Types

Request Events

[:http_fetch, :request, :start] - Emitted when a request begins

• Measurements: %{start_time: integer} (microseconds)
• Metadata: %{method: atom, url: URI.t(), headers: HTTP.Headers.t()}

[:http_fetch, :request, :stop] - Emitted when a request completes successfully

• Measurements: %{duration: integer, status: integer, response_size: integer}
  • duration - Request duration in microseconds
  • status - HTTP status code
  • response_size - Response body size in bytes
• Metadata: %{url: URI.t(), status: integer}

[:http_fetch, :request, :exception] - Emitted when a request fails

• Measurements: %{duration: integer} (microseconds)
• Metadata: %{url: URI.t(), error: term()}

Streaming Events

[:http_fetch, :streaming, :start] - Emitted when response streaming begins

• Measurements: %{content_length: integer} (0 if unknown)
• Metadata: %{}

[:http_fetch, :streaming, :chunk] - Emitted for each stream chunk received

• Measurements: %{bytes_received: integer, total_bytes: integer}
• Metadata: %{}

[:http_fetch, :streaming, :stop] - Emitted when streaming completes

• Measurements: %{total_bytes: integer, duration: integer} (duration in microseconds)
• Metadata: %{}

Response Body Events

[:http_fetch, :response, :body_read_start] - Emitted when reading response body

• Measurements: %{content_length: integer}
• Metadata: %{}

[:http_fetch, :response, :body_read_stop] - Emitted when body read completes

• Measurements: %{bytes_read: integer, duration: integer}
• Metadata: %{}

HTTP/2 Runtime Events

[:http_fetch, :http2, :connection] reports active_streams, protocol_streams, buffered_receive_bytes, pending_upload_bytes, receive_budget_bytes, and writer_batch_peak_bytes. Metadata contains only event and lifecycle; it excludes headers, bodies, URLs, scope and TLS identity. Events are emitted on stream admission/release, receive admission/consumption, and connection termination. Receive bytes include padding and deliveries awaiting application acknowledgement; upload bytes count pending owner slices. BodyBridge separately exposes its bounded source-chunk budget through status/1.

[:http_fetch, :http2, :pool] reports aggregate reservations, waiters, connecting, connections, draining, and queue_wait_us measurements. Metadata contains only finite event and outcome atoms. Pool keys, URLs, request tokens, owner PIDs, and connector identities are excluded.

[:http_fetch, :http2, :runtime] reports connection close, peer reset, GOAWAY, and upload flow-control stall events. Metadata contains only fixed event and outcome atoms. Peer error codes and stall durations are numeric measurements, never tags. [:http_fetch, :http2, :body_bridge] reports a bridge's final byte count, peak buffer size, and lifetime in microseconds; its outcome is a fixed atom, with no source or owner identity.

Usage Example

# Attach a simple logger handler
:telemetry.attach_many(
  "http-logger",
  [
    [: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("Request started: " <> to_string(metadata.url))

      [:http_fetch, :request, :stop] ->
        duration_ms = measurements.duration / 1000
        IO.puts("Request completed in " <> Float.to_string(duration_ms) <> "ms")

      [:http_fetch, :request, :exception] ->
        IO.puts("Request failed: " <> inspect(metadata.error))
    end
  end,
  nil
)

Metrics Collection

# Collect request duration metrics
:telemetry.attach(
  "http-metrics",
  [:http_fetch, :request, :stop],
  fn _event, measurements, metadata, _config ->
    # Send to your metrics system
    MyMetrics.record_http_request(
      url: to_string(metadata.url),
      status: metadata.status,
      duration_us: measurements.duration
    )
  end,
  nil
)

Integration with Telemetry.Metrics

# Define metrics for visualization
import Telemetry.Metrics

[
  # Request duration histogram
  distribution("http_fetch.request.duration",
    unit: {:native, :millisecond},
    tags: [:status]
  ),

  # Request count by status
  counter("http_fetch.request.count",
    tags: [:status]
  ),

  # Response size summary
  summary("http_fetch.request.response_size",
    unit: :byte
  ),

  # Streaming throughput
  distribution("http_fetch.streaming.chunk.bytes_received",
    unit: :byte
  )
]