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.

Request metadata contains only finite method, scheme, protocol and error categories plus numeric status. Headers and all URI components (including host, path, userinfo, query and fragment) are omitted. Arbitrary exception details are replaced with :request_failed.

Pass telemetry: false to HTTP.fetch/2 to suppress request events and its response streams and internally created upload streams/bridges. A producer stream created independently before the request has its own telemetry setting. Shared HTTP/2 connection/pool events contain only safe aggregate measurements and finite categories and remain independent of a single request's option. For a strict global opt-out, configure config :http_fetch, telemetry: false; this suppresses both [:http_fetch, ...] and the shared runtime's [:http_runtime, ...] events, including other clients using that runtime. config :http_runtime, telemetry: false independently suppresses all shared runtime events. The bundled TLS and QUIC engines emit no telemetry events.

Event Types

Request Events

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

• Measurements: %{start_time: integer} (microseconds)

• Metadata: %{method: atom, scheme: :http | :https | :other}

[: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: %{scheme: atom, status: integer, http_version: atom}

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

• Measurements: %{duration: integer} (microseconds)
• Metadata: %{scheme: atom, error: atom}

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: " <> Atom.to_string(metadata.scheme))

      [: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(
      scheme: metadata.scheme,
      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
  )
]