[client-v2,jdbc-v2] Metrics

[chernser]

Description

Client should report different metrics that is currently collected. However it is not done automatically using 011y tools. We need to implement SPI that make it possible to use any metric exporter adapter.

[polyglotAI-bot]

Design questions before implementation

I looked at what the client collects today and at the span-recorder SPI (#2974 / #2988, plus the separate OTel adapter module in #3065) as the model. The metrics SPI has several viable shapes with materially different trade-offs, and the public API it introduces sets a precedent that is hard to change later. Rather than guess, here are the options and a recommendation.

What exists today

• OperationMetrics (client-v2) — per-operation values: ClientMetrics.OP_DURATION, OP_SERIALIZATION, and the server progress summary (ServerMetrics.RESULT_ROWS, NUM_ROWS_READ, NUM_BYTES_READ, NUM_ROWS_WRITTEN, NUM_BYTES_WRITTEN). Returned to the caller, never exported.
• Client.Builder.registerClientMetrics(Object registry, String name) + MicrometerLoader — Micrometer only, and only HTTP connection-pool gauges (pull-based). Throws for a non-Micrometer registry.
• SpanRecorder — a backend-agnostic push SPI, called first with everything the client knows, with SpanSupport deriving the standard OTel names/attributes and DefaultSpanRecorder as a no-op base.
• jdbc-v2 — no metrics surface at all; it builds a Client from connection properties (JdbcConfiguration#applyClientProperties).

Decision 1 — SPI shape

• (A) Event recorder, mirroring SpanRecorder. MetricsRecorder with methods such as recordQuerySuccess(QuerySettings, OperationMetrics), recordInsertSuccess(...), recordFailure(...), recordRequest(...); a MetricsSupport helper that derives the standard metric names, units and attributes; a no-op DefaultMetricsRecorder base so a recorder keeps working when the client starts reporting something new. Adapter maps events onto Micrometer/OTel instruments.
  Pro: symmetric with the tracing SPI already merged, one pattern to learn, the client stays free of instrument concepts, additive and non-breaking. Con: push only — it cannot express pull-based gauges (connection pool), so those keep a separate path.
• (B) Instrument registry abstraction. The client declares its own Counter / Histogram / Gauge handles from a MeterProvider-like SPI; adapters implement the instruments.
  Pro: covers pull gauges and push counters in one mechanism; adapters are thin. Con: a much wider API surface to specify and keep stable (units, cardinality, instrument lifecycle), diverges from the tracing SPI.
• (C) Micrometer-only, extend the existing registerClientMetrics. Pro: smallest change. Con: not the requested "any exporter adapter".

Recommendation: (A), for symmetry with #2988 and because most of what is asked for is per-operation event data.

Decision 2 — which metrics, and whose naming

Proposed set: operation duration, serialization duration, operation count by outcome, rows/bytes read, rows/bytes written, transport requests including retries, and failures by ClickHouse error code / HTTP status.

Naming: follow the OpenTelemetry database-client semantic conventions where they exist (db.client.operation.duration as a histogram in seconds, attributes db.system.name, db.namespace, db.operation.name, error.type), and put anything without a convention under clickhouse.* — the same rule SpanAttribute already follows. Note this makes the unit seconds, while ClientMetrics.OP_DURATION is milliseconds.

Question: is that metric set right, and do you want OTel semconv names/units, or client-native names (client.opDuration, milliseconds) for consistency with ClientMetrics?

Decision 3 — how it is activated in jdbc-v2

A JDBC URL carries only strings, so a recorder instance cannot be passed through it.

• (A) ServiceLoader discovery — a recorder on the classpath is picked up with no configuration. Zero-config for URL-only setups, but implicit.
• (B) Class-name property (e.g. metrics_recorder=com.acme.MyRecorder, instantiated reflectively with a public no-arg constructor) — explicit and per-connection.
• (C) Programmatic only (Client.Builder.setMetricsRecorder(...), reachable from jdbc-v2 only through the DataSource/Properties path) — simplest, but the plain URL case gets nothing, and the issue names jdbc-v2 explicitly.

Recommendation: (B) plus programmatic, with (A) as a later addition if wanted.

Decision 4 — adapters, and the existing Micrometer path

• Ship adapters in this PR, or the SPI first and adapters later? If shipped, a separate module per adapter (as feat(client-v2-otel): add OpenTelemetry span recorder module #3065 did for OTel spans) keeps the dependencies out of client-v2 and clickhouse-jdbc-all.
• Keep registerClientMetrics / MicrometerLoader as is for connection-pool gauges (pull-based, out of reach of a push SPI), or deprecate it in favour of the new SPI?

Everything proposed is additive and Java 8 compatible; no existing behaviour changes.

What I need to proceed

Confirmation on 1 (shape), 2 (metric set + naming convention), 3 (jdbc-v2 activation) and 4 (adapter scope + fate of registerClientMetrics). With those settled I will implement it in one PR with tests for both client-v2 and jdbc-v2, plus docs/features.md and a CHANGELOG entry.

[chernser]

@polyglotAI-bot

1. • option A. Same as span recorder.
2. we need only operation duration, serialization duration, operation count by outcome, number of retries. follow open telemetry semantic
3. • option B
4. • SPI first then implementation for micrometer/otel

[chernser]

@polyglotAI-bot SPI PR is merged please continue with micrometer changes