ClientMiddleware: document the caveats

[iRevive]

ClientMiddleware could be tricky and doesn't always meet expectations.

val client: Client[IO] = ClientMiddleware.default[IO].build(...)
client.run(request).use(response => Tracer[IO].currentSpanContext.debug()) // prints None

I'm almost sure that most people would expect Tracer[IO].currentSpanContext.debug() to print an active span context there.
However, it does not work that way due to limitations: 1, 2.

What can we do?

1. Document why it doesn't work
2. Provide a workaround

A workaround could be the following:

1. A text map propagator (e.g. W3CContextPropagator) must be enabled to make this work
2. Add tracing headers to the response: resp.withHeaders(traceHeaders ++ resp.headers)
3. A user must explicitly join the active span via Tracer[F].joinOrRoot:

client.run(request).use { response =>
  Tracer[IO].joinOrRoot(response.headers)(
    tracer.currentSpanContext.debug() // prints an active span context, all good
  )
}

---

This is not the case with the ServerMiddleware because HttpRoutes isn't described as a Resource but as Kleisli.

[iRevive]

@rossabaker @NthPortal how can we mitigate this limitation in your opinion?

[NthPortal]

I'm not convinced this is a bug. the tracing from the middleware is around the client making the request, and using the resource of the response is not part of that

[iRevive]

It's not a bug, but it may be an unexpected behavior for newcomers.

the tracing from the middleware is around the client making the request

You are right. That makes sense.