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. +