From c2e8d4fff8a899e46928ec8ba38e8101fcea199a Mon Sep 17 00:00:00 2001 From: Ralph Ursprung Date: Wed, 4 Nov 2026 10:04:45 +0100 Subject: [PATCH] Document explicit connection pool metrics Distinguish pool gauges installed by `enable(...)` from lease metrics recorded by the explicit connection manager wrappers in HttpClient 5.7. The existing API supports both without changing builder behavior. Add classic usage and a generic async library callback example. Explain configuration order, pool settings, repeated wrapping, and ownership. Link the guide from the existing observation page and site navigation. This is the outcome of the discussion in apache/httpcomponents-client#908 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../observation.md | 16 +- .../httpcomponents-client-5.7.x/index.md | 3 +- .../observation.md | 150 ++++++++++++++++++ src/site/site.xml | 1 + 4 files changed, 164 insertions(+), 6 deletions(-) create mode 100644 src/site/markdown/httpcomponents-client-5.7.x/observation.md diff --git a/src/site/markdown/httpcomponents-client-5.6.x/observation.md b/src/site/markdown/httpcomponents-client-5.6.x/observation.md index 8b4665c..c7cd754 100644 --- a/src/site/markdown/httpcomponents-client-5.6.x/observation.md +++ b/src/site/markdown/httpcomponents-client-5.6.x/observation.md @@ -37,8 +37,9 @@ How it fits: `enable(...)` helpers. The observation module is separate; core HttpClient has no hard dependency. - **Classic, Async, and Caching** are all supported. For caching builders, interceptors are inserted **after** the caching stage so metrics reflect the effective exchange. -- **Low friction.** A single call wires timers/counters and, if you want them, pool gauges, DNS/TLS meters, - and observation spans. You keep full control via two small configs: +- **Explicit instrumentation.** `enable(...)` installs request metrics and observations. + With `CONN_POOL` enabled, it also binds gauges to an attached pooling connection manager. + DNS and TLS metrics require separate wrappers. You keep full control via two small configs: - `ObservingOptions` – choose metric groups (BASIC, IO, CONN_POOL, TLS, DNS), tag level (`LOW` for minimal, `EXTENDED` for richer tags), per-URI sampling, and a tag customizer hook. - `MetricConfig` – set the metric name prefix (`http.client` by default), SLO bucket(s), percentiles, optional @@ -53,13 +54,18 @@ How it fits: Typical flow: 1. Add `httpclient5-observation` and whichever Micrometer bits you actually use (all Micrometer deps can stay `optional`). -2. Build your client as usual; call `HttpClientObservationSupport.enable(...)` on the builder - (classic/async/caching variants provided). -3. (Optional) Bind **pool gauges** after you’ve attached a pooling connection manager. +2. If you need pool gauges, attach a pooling connection manager to the builder. +3. Call `HttpClientObservationSupport.enable(...)` before you build the client + (classic/async/caching variants provided). Include `CONN_POOL` to bind pool gauges. 4. (Optional) Wrap your DNS resolver with `MeteredDnsResolver` and your TLS strategy with `MeteredTlsStrategy` if you want those timing/outcome meters as well. 5. (Optional) Bridge the `ObservationRegistry` to OpenTelemetry to get client spans alongside metrics. +`enable(...)` does not wrap or replace the connection manager. +Pool gauges report the current pool state, not lease wait times or lease counts. +Since 5.7, explicit connection manager wrappers provide those lease metrics. +See [connection pool metrics](../httpcomponents-client-5.7.x/observation.md) for classic and async usage, including a generic library builder callback. + Practical notes: - **Naming:** all meters are prefixed by `MetricConfig.prefix` (default `http.client`). Examples: diff --git a/src/site/markdown/httpcomponents-client-5.7.x/index.md b/src/site/markdown/httpcomponents-client-5.7.x/index.md index 7e0003e..df4964f 100644 --- a/src/site/markdown/httpcomponents-client-5.7.x/index.md +++ b/src/site/markdown/httpcomponents-client-5.7.x/index.md @@ -49,6 +49,7 @@ Documentation 1. Guides * [Getting started](getting-started.md) + * [Connection pool metrics](observation.md) - Explicit lease instrumentation and library builder callbacks * [SSE](server-sent-events.md) - Server side events * [Jakarta REST client](rest-client.md) - Type-safe Jakarta REST client backed by HttpClient * [WebSocket](websocket.md) - Full-duplex messaging over HTTP/1.1 and HTTP/2 @@ -125,4 +126,4 @@ Engineering Task Force (IETF) and the internet at large: - [RFC 8297](https://datatracker.ietf.org/doc/html/rfc8297) – Early Hints status code - [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455) - The WebSocket Protocol - [RFC 7692](https://datatracker.ietf.org/doc/html/rfc7692) - Compression Extensions for WebSocket (permessage-deflate) -- [RFC 8441](https://datatracker.ietf.org/doc/html/rfc8441) - Bootstrapping WebSockets with HTTP/2 \ No newline at end of file +- [RFC 8441](https://datatracker.ietf.org/doc/html/rfc8441) - Bootstrapping WebSockets with HTTP/2 diff --git a/src/site/markdown/httpcomponents-client-5.7.x/observation.md b/src/site/markdown/httpcomponents-client-5.7.x/observation.md new file mode 100644 index 0000000..71d14de --- /dev/null +++ b/src/site/markdown/httpcomponents-client-5.7.x/observation.md @@ -0,0 +1,150 @@ + + +# Connection pool metrics + +The optional `httpclient5-observation` module provides Micrometer metrics for connection pools. +For dependencies and request metrics, see the [observability guide](../httpcomponents-client-5.6.x/observation.md). +The connection manager wrappers in this guide require HttpClient 5.7 or later. +Use the same version for `httpclient5` and `httpclient5-observation`. + +A lease is a request to obtain a connection. +A gauge reports a current value, such as the number of pending leases. +Lease timers measure the wait for a connection, not the duration of an HTTP request. + +With `ObservingOptions.MetricSet.CONN_POOL` enabled, the API provides two separate forms of measurement: + +| Metrics | How to enable them | +|---------|--------------------| +| `.pool.leased`, `.pool.available`, `.pool.pending` gauges | Attach a pooling connection manager to the builder, then call `HttpClientObservationSupport.enable(...)`. | +| `.pool.lease` timer and `.pool.leases` counter | Wrap the manager with `meteredConnectionManager(...)` or `meteredAsyncConnectionManager(...)`, then attach the returned manager to the builder. | + +`` comes from `MetricConfig.prefix` and defaults to `http.client`. +The lease timer and counter have a `result` tag. +`ObservingOptions.TagLevel.EXTENDED` also adds a `target` tag with the target hostname. +Lease meters appear after lease outcomes occur, rather than when you configure the builder. + +`enable(...)` does not create, wrap, or replace a connection manager. +It binds gauges to the manager that is attached when you call it. +If no manager is attached, it does not bind pool gauges. +The default manager that `build()` creates later does not receive pool instrumentation. + +## Classic client + +Create and configure the pool, wrap it once, and attach the returned manager before you call `enable(...)`. +Use the same registry, observation options, and metric configuration for both calls. +The following example enables request metrics, pool gauges, and lease metrics without tracing. + +```java +import java.util.EnumSet; + +import io.micrometer.core.instrument.simple.SimpleMeterRegistry; +import org.apache.hc.client5.http.impl.classic.HttpClients; +import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder; +import org.apache.hc.client5.http.observation.HttpClientObservationSupport; +import org.apache.hc.client5.http.observation.MetricConfig; +import org.apache.hc.client5.http.observation.ObservingOptions; + +final var meters = new SimpleMeterRegistry(); +final var options = ObservingOptions.builder() + .metrics(EnumSet.of( + ObservingOptions.MetricSet.BASIC, + ObservingOptions.MetricSet.CONN_POOL)) + .build(); +final var metricConfig = MetricConfig.DEFAULT; +final var pool = PoolingHttpClientConnectionManagerBuilder.create().build(); +final var meteredManager = HttpClientObservationSupport.meteredConnectionManager( + pool, meters, options, metricConfig); +final var builder = HttpClients.custom().setConnectionManager(meteredManager); + +HttpClientObservationSupport.enable( + builder, null, meters, options, metricConfig); +final var client = builder.build(); +``` + +Keep the client and registry for the lifetime of the application component that owns them. +Close the client when that component stops, then close the registry if no other component uses it. +By default, the client closes its connection manager, and the wrapper forwards that close to the pool. + +For an async client, use `PoolingAsyncClientConnectionManagerBuilder`, `meteredAsyncConnectionManager(...)`, and `HttpAsyncClients.custom()` in the same order. +Start the async client before you execute requests. +The same explicit wrapping and configuration order apply to caching client builders. + +## Library builder callbacks + +A library can expose a callback for configuring its HttpClient builder without exposing its connection manager. +In that callback, you can supply your own metered manager through `setConnectionManager(...)`. +You do not need to change HttpClient or the library to record lease metrics. + +The following generic callback accepts an async builder and returns the same builder after configuration. +It uses the `meters`, `options`, and `metricConfig` from the classic example. +Use this callback instead of creating the classic client. + +```java +import java.util.function.UnaryOperator; + +import org.apache.hc.client5.http.impl.async.HttpAsyncClientBuilder; +import org.apache.hc.client5.http.impl.nio.PoolingAsyncClientConnectionManagerBuilder; + +final UnaryOperator configureHttpClient = + clientBuilder -> { + final var pool = PoolingAsyncClientConnectionManagerBuilder.create() + .build(); + final var meteredManager = + HttpClientObservationSupport.meteredAsyncConnectionManager( + pool, meters, options, metricConfig); + clientBuilder.setConnectionManager(meteredManager); + HttpClientObservationSupport.enable( + clientBuilder, null, meters, options, metricConfig); + return clientBuilder; + }; +``` + +Register equivalent configuration through the library's callback API. +`UnaryOperator` describes the callback's input and output here, not a required callback type for the library. +If the library attaches a manager before it invokes the callback, this configuration replaces that manager. + +Before you build the new pool, configure its required pool limits and connection timeouts. +Apply any required TLS strategy and DNS resolver to this pool. +Settings on the original manager do not transfer to the replacement. +Library callbacks that configure the original manager do not configure this replacement. +Keep other client configuration, such as authentication, in the same callback. + +Do not build or start the HttpClient inside the callback. +Let the library build, start, and close its client according to its lifecycle contract. +If the library changes the connection manager after the callback, use a configuration hook that retains your metered manager. + +## Configuration and ownership + +Wrap a manager only once. +The helpers do not detect an existing metered wrapper, so wrapping again records each lease more than once. +If `CONN_POOL` is disabled, the helpers return the original manager without lease instrumentation. + +Use a pooling manager for pool gauges. +The wrappers implement `ConnPoolControl` even when their underlying manager does not support pooling. +With a non-pooling manager, their pool statistics are zero and do not describe an actual pool. + +Do not replace the manager after you call `enable(...)`. +The gauges remain bound to the manager that was attached at that time. +If you need only gauges, attach the unwrapped pool before `enable(...)` and omit the wrapper. + +Wrapping does not change the builder's `setConnectionManagerShared(...)` setting. +If you share a manager across clients, set `setConnectionManagerShared(true)` and close the manager after all clients stop. +If several pools share a registry, give each pool a distinct metric prefix or common tags. +These identifiers keep each pool's gauges separate. diff --git a/src/site/site.xml b/src/site/site.xml index 8f1b756..9f05546 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -93,6 +93,7 @@ under the License. +