Document that http.client.requests measure the entire HTTP exchange

[mateusz-nalepa]

Hello! 👋

Context

https://docs.spring.io/spring-boot/reference/actuator/metrics.html#actuator.metrics.supported.http-clients
By looking at the description of client metric, I wouldn't say, that http.client.requests metric includes things like eq: waiting for connection in connection pool.
Sometimes i see Spikes for dashboards with this metric and i would like to know, that those SPIKE's may be visible due to requests waiting in queue or something else.

In order to have only request time, I need to measure request time on RequestFactory level.

Example

Spring Boot Version - 3.4.1

I've prepared an small example, where I'm executing 4 requests with connection pool size equal to 2 and response from wiremock stub equal to 50ms. Here's the code: https://github.com/mateusz-nalepa/communication-errors/blob/main/src/test/kotlin/com/mateusz/nalepa/communicationerrors/timeout/queue/ConnectionRequestTimeoutWaitingInQueue.kt#L107

Here's the results:

Single request took: 52 ms
http.client metric duration value: 53.469458ms
Single request took: 54 ms
http.client metric duration value: 54.166459ms
Single request took: 54 ms
Single request took: 53 ms
http.client metric duration value: 108.194083ms
http.client metric duration value: 108.211042ms

So as you can see, those last two request contains of:

• request itself
• waiting in queue

Proposal

I would like to add some tip for documentation like:

This metric is not applied on the particular Request Factory. 
So value of this metric is not always equal to request itself. 
As a part of this metric there can be for example: waiting for connection from connection pool.

Question

What do you think?
Please let me know! 😄

[bclozel]

The current documentation for http.client.requests says "Time spent for HTTP client exchanges". I believe this is an accurate description as this involves the entire exchange: from connection establishment up to body deserialization. Since the instrumentation is done at the WebClient/RestClient/RestTemplate level, I assume that it's natural to measure the time spent within method calls on those types. Depending on the HTTP library being used, there might not be a connection pool at all.

We could add a short sentence here stating that. Would this work for you?

[mateusz-nalepa]

The current documentation for http.client.requests says "Time spent for HTTP client exchanges".

Yup, it's true. But what, if you don't know what the exchange really is?
Few years ago I've watched a brilliant presentation GeeCON 2017: Adam Dubiel - HTTP clients: silent heroes of distributed systems which explained this topic. So i would say, that it's easier to understand numbers, when you have an idea how things works under the hood.

We could add a short sentence here stating that. Would this work for you?

Yes!