Skip to content

Meter pool leases automatically when CONN_POOL is on - #908

Closed
rursprung wants to merge 1 commit into
apache:masterfrom
rursprung:observation-auto-metered-conn-manager
Closed

rursprung wants to merge 1 commit into
apache:masterfrom
rursprung:observation-auto-metered-conn-manager

Conversation

@rursprung

@rursprung rursprung commented Oct 28, 2026 •

Copy link
Copy Markdown

(full disclosure: AI-generated, reviewed by me)

HttpClientObservationSupport.enable(...) with MetricSet.CONN_POOL only bound the pool gauges. The <prefix>.pool.lease timer and the <prefix>.pool.leases counter were recorded only if the caller wrapped the connection manager explicitly with meteredConnectionManager() or meteredAsyncConnectionManager(). This is not possible when a library creates the connection manager internally and only exposes the builder, for example ApacheHttpClient5TransportBuilder in opensearch-java.

All enable(...) variants (classic, async and caching) now replace the connection manager of the builder with the metered wrapper and bind the pool gauges to it:

  • A manager that is already a MeteredConnectionManager or a MeteredAsyncConnectionManager is not wrapped again, so explicit wrapping and repeated enable(...) calls stay safe.
  • The connection manager shared flag is not changed.
  • Pool gauges are bound only if the original manager is a ConnPoolControl, as before.
  • If no connection manager is set on the builder, no pool metrics are installed, as before. The default manager that build() creates is not instrumented.
  • If CONN_POOL is disabled, nothing changes.

`HttpClientObservationSupport.enable(...)` with `MetricSet.CONN_POOL`
only bound the pool gauges. The `<prefix>.pool.lease` timer and the
`<prefix>.pool.leases` counter were recorded only if the caller wrapped
the connection manager explicitly with `meteredConnectionManager()` or
`meteredAsyncConnectionManager()`. This is not possible when a library
creates the connection manager internally and only exposes the builder,
for example `ApacheHttpClient5TransportBuilder` in `opensearch-java`.

All `enable(...)` variants (classic, async and caching) now replace the
connection manager of the builder with the metered wrapper and bind the
pool gauges to it:

- A manager that is already a `MeteredConnectionManager` or a
  `MeteredAsyncConnectionManager` is not wrapped again, so explicit
  wrapping and repeated `enable(...)` calls stay safe.
- The connection manager shared flag is not changed.
- Pool gauges are bound only if the original manager is a
  `ConnPoolControl`, as before.
- If no connection manager is set on the builder, no pool metrics are
  installed, as before. The default manager that `build()` creates is
  not instrumented.
- If `CONN_POOL` is disabled, nothing changes.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@ok2c
ok2c requested a review from arturobernalg October 29, 2026 15:30
@arturobernalg

Copy link
Copy Markdown
Member

@rursprung
I am not convinced we should automatically replace the connection manager when CONN_POOL metrics are enabled.

We already provide explicit wrappers for lease instrumentation. Making enable() modify the connection manager introduces additional complexity and depends on configuration order and internal builder APIs. It also does not cover the default connection manager.

I understand the OpenSearch use case, but I would rather keep connection manager instrumentation explicit than introduce this implicit behavior.

There is also a reproducible issue with repeated enable() calls: a non-pooling manager ends up exposing pool gauges because the metered wrapper implements ConnPoolControl.

I would prefer a more explicit approach that addresses the original use case without changing the existing enable() semantics.

@rursprung

Copy link
Copy Markdown
Author

I would prefer a more explicit approach that addresses the original use case without changing the existing enable() semantics.

thanks for your review! do you have something specific in mind for this so that i don't go off in the wrong direction?

@arturobernalg

Copy link
Copy Markdown
Member

I think we should keep connection manager instrumentation explicit.

The OpenSearch use case can already be handled in the builder callback using meteredAsyncConnectionManager() and setConnectionManager(). I verified that this correctly records lease metrics and pool gauges.

Automatically replacing the connection manager in enable() introduces configuration-order dependencies and changes the builder’s behavior. It also causes incorrect pool gauges with non-pooling managers when enable() is called repeatedly.

I do not think the additional complexity is justified. I would prefer to close this PR and document the explicit approach instead.

@rursprung

Copy link
Copy Markdown
Author

ok thanks for looking into this!
i've raised apache/httpcomponents-website#51. i wasn't exactly sure how you want to structure your documentation (regarding 5.6 and 5.7), looking forward to your feedback there!

do you think any javadoc extensions are needed in this repo here as well?

@rursprung rursprung closed this Nov 4, 2026
@rursprung
rursprung deleted the observation-auto-metered-conn-manager branch November 4, 2026 09:18
arturobernalg pushed a commit to apache/httpcomponents-website that referenced this pull request Nov 21, 2026
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants