A wrapping http.RoundTripper times RoundTrip — what span of the outbound call does that measure?

## Where a transport wrapper sits `http.RoundTripper` is a one-method interface: `RoundTrip(*http.Request) (*http.Response, error)`. An `http.Client` holds one in its `Transport` field, and everything the client does around it — following redirects, applying the cookie jar, enforcing `Client.Timeout` — happens *above* the transport. Wrapping it is the standard way to instrument every outbound call a service makes without touching call sites: ```go type timingTransport struct{ base http.RoundTripper } func (t *timingTransport) RoundTrip(req *http.Request) (*http.Response, error) { start := time.Now() resp, err := t.base.RoundTrip(req) recordUpstream(req.URL.Host, time.Since(start), err) return resp, err } ``` ## What is inside the measured span When the base transport is `http.Transport`, one `RoundTrip` covers: - **Connection acquisition** — waiting for a free connection if the per-host limit is reached, and, when a new one is needed, the DNS lookup, the TCP dial and the TLS handshake. - **Writing the request**, including its body. - **Waiting for the response status line and headers to arrive and be parsed.** It also covers the transport's own internal retry of an idempotent request when it discovers the idle connection it picked was closed by the peer — that retry happens inside a single `RoundTrip`. ## What is outside it `RoundTrip` returns as soon as the headers are parsed. `resp.Body` is an open stream connected to the network; the bytes have not arrived. Everything the caller then does — `io.Copy`, `json.NewDecoder(resp.Body).Decode(&v)`, draining and closing — happens after your timer has stopped. For a small JSON reply the difference is noise. For a paginated dump, a slow upstream trickling rows, or a proxied download, the metric will confidently report 8ms for a call that occupied the goroutine for four seconds. Two more things live outside the span. Redirects: `http.Client` issues a fresh request for each hop, so three `RoundTrip` durations exist where the caller saw one `Do`. And `Client.Timeout`, which covers the whole exchange including the body read — a call can therefore fail on that timeout with a perfectly healthy `RoundTrip` duration recorded. ## Measuring the rest Because `resp.Body` is just an `io.ReadCloser`, you can swap it for a wrapper that reports when the caller is finished: ```go type timedBody struct { io.ReadCloser done func() } func (b *timedBody) Close() error { b.done() return b.ReadCloser.Close() } ``` Set `resp.Body = &timedBody{ReadCloser: resp.Body, done: ...}` before returning, and you get a second measurement covering the drain. It depends on the caller actually closing the body, which it must do anyway to release the connection back to the pool, so a missing measurement is itself a useful signal of a leaked body. ## What not to do inside RoundTrip Do not read the body inside your wrapper to time it: the caller expects an unread stream and would get an empty one. Do not modify the request in place either — the documented contract is that `RoundTrip` must not modify the request; clone it (`req.Clone(ctx)`) if you need to change anything. And keep the work small: this code runs on every outbound call, including the hot ones. ## Which number answers which question For a service fanning one inbound request out to several upstreams, the time-to-headers number tells you whether an upstream is slow to *decide*, and the time-to-drained number tells you whether it is slow to *deliver*. They fail differently and they are fixed differently, which is exactly why it is worth being able to say which one your dashboard is showing.