Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 11 additions & 5 deletions src/site/markdown/httpcomponents-client-5.6.x/observation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
3 changes: 2 additions & 1 deletion src/site/markdown/httpcomponents-client-5.7.x/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
- [RFC 8441](https://datatracker.ietf.org/doc/html/rfc8441) - Bootstrapping WebSockets with HTTP/2
150 changes: 150 additions & 0 deletions src/site/markdown/httpcomponents-client-5.7.x/observation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->

# 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 |
|---------|--------------------|
| `<prefix>.pool.leased`, `<prefix>.pool.available`, `<prefix>.pool.pending` gauges | Attach a pooling connection manager to the builder, then call `HttpClientObservationSupport.enable(...)`. |
| `<prefix>.pool.lease` timer and `<prefix>.pool.leases` counter | Wrap the manager with `meteredConnectionManager(...)` or `meteredAsyncConnectionManager(...)`, then attach the returned manager to the builder. |

`<prefix>` 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<HttpAsyncClientBuilder> 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.
1 change: 1 addition & 0 deletions src/site/site.xml
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ under the License.
</item>
<item name="HttpClient 5.7 BETA" collapse="true" href="httpcomponents-client-5.7.x/index.html">
<item name="Getting started" href="httpcomponents-client-5.7.x/getting-started.html"/>
<item name="Connection pool metrics" href="httpcomponents-client-5.7.x/observation.html"/>
<item name="Download" href="httpcomponents-client-5.7.x/download.html"/>
</item>
<item name="HttpCore 5.4" collapse="true" href="httpcomponents-core-5.4.x/index.html">
Expand Down