Req Tele

Note

This project is a fork of req_telemetry by Zach Allaun, maintained and published independently. It includes community contributions from the original repository.

Req plugin to instrument requests with :telemetry events.

Usage

Preferably, ReqTele should be the last plugin attached to your %Req.Request{}. This allows ReqTele to emit events both at the very start and very end of the request and response pipelines. In this way, you can observe both the total time spent issuing and processing the request and response, as well as the time spent only with the request adapter.

req = Req.new() |> ReqTele.attach()

req =
  Req.new(adapter: MyAdapter)
  |> ReqSomeOtherThing.attach()
  |> ReqTele.attach()

Events

ReqTele produces the following events (in order of event dispatch):

[:req, :request, :pipeline, :start]
[:req, :request, :adapter, :start]
[:req, :request, :adapter, :stop]
[:req, :request, :adapter, :error]
[:req, :request, :pipeline, :stop]
[:req, :request, :pipeline, :error]

You can configure ReqTele to produce only :pipeline or :adapter events; see ReqTele.attach/2 for options.

All events carry a :ref and an :attempt in their metadata.

The :ref identifies the logical request and stays the same for all of its events, so a :start event can be paired with the :stop or :error event that closes it.

Retries and redirects run the request through the adapter several times, and :attempt counts those runs, starting at 1. Each run emits its own pair of :adapter events, while the :pipeline events wrap the whole request: [:req, :request, :pipeline, :start] is emitted for the first attempt, and its duration covers every attempt along with the delays between them. Handlers that track one span per request can key on :ref alone, and handlers that track individual HTTP calls can key on {ref, attempt}.

Logging

ReqTele defines a simple, default logger that logs basic request information and timing.

Here's how a successful request might be logged:

Req:479128347 - GET https://example.org (pipeline)
Req:479128347 - GET https://example.org (adapter)
Req:479128347 - 200 in 403ms (adapter)
Req:479128347 - 200 in 413ms (pipeline)

For usage and configuration, see ReqTele.attach_default_logger/1.

Installation

req_tele is available through hex.pm, and can be installed by adding the following to your list of dependencies:

defp deps do
  [
    {:req_tele, "~> 0.3"},
  ]
end