Proposal: Prometheus HTTP API client module (prometheus-metrics-api-client)

Bắt đầu với phạm vi được đề xuất và các câu hỏi còn bỏ ngỏ trong issue #2306, sau đó xem xét các quy ước của module client_java hiện có trước khi triển khai. Một kết quả hoàn chỉnh sẽ định nghĩa module, các model và request có kiểu của Prometheus API, các tùy chọn xác thực và TLS, các bài kiểm thử tích hợp với các backend tương thích với Prometheus, cùng tài liệu.

What

A new module — working name prometheus-metrics-api-client — providing a typed Java client for the Prometheus HTTP API (/api/v1/*): instant and range queries, series / labels / metadata, with a typed result model (vector / matrix / scalar / string).

Why revisit this

I'm aware querying has historically been considered out of scope here (#816, #841 — "client_java is for exposing metrics"). Three reasons I think it's worth revisiting:

1. The reference Go client already ships one. client_golang/api/prometheus/v1 provides Query, QueryRange, Series, LabelNames, LabelValues, Metadata, Rules, Targets and more, inside the official client library. So "client libraries are instrumentation-only" isn't consistent across official Prometheus clients — Go users get an API client out of the box, JVM users don't.

2. There is no maintained JVM alternative, so everyone hand-rolls. GitHub code search for "api/v1/query_range" language:Java returns ~350 files. A sample of projects each maintaining their own HTTP + JSON model code for the same API: LinkedIn Cruise Control, Spinnaker Kayenta, OpenSearch SQL, YugabyteDB, Apache SeaTunnel, Kruize, DataStax Fallout. The third-party libraries that exist are unmaintained one-person projects:

• mckang/promql_java_client — the closest thing to a full client (★89), but a single-contributor project: essentially all code dates from 2022, with sporadic commits since.
• DanielMager/PrometheusQueries4J — single contributor, no commits since 2022.
• HolgerZhang/promql-builder — PromQL query-string builder only, no HTTP/JSON layer.
• …plus assorted single-author experiments (PromQLGenerator, PQLetta).

3. Hand-rolling keeps producing the same spec-compliance bugs. Current example: linkedin/cruise-control#2389 — timestamps formatted via Double.toString() come out in scientific notation (start=1.784144612388E9). Prometheus happens to accept that (Go's lenient ParseFloat), but stricter API-compatible backends (VictoriaMetrics) reject it with 422. A shared, well-tested client fixes this class of bug once for the whole ecosystem instead of once per project.

Proposed scope (v1)

• Endpoints: query, query_range, series, labels, label/<name>/values, metadata — the subset that virtually every hand-rolled client reimplements; client_golang's surface as the ceiling, added on demand.
• Typed result model: vector / matrix / scalar / string; spec-compliant request encoding (plain-decimal or RFC 3339 timestamps, POST for long queries).
• Auth: basic, bearer token, custom headers (e.g. X-Scope-OrgID for Mimir), TLS config.
• Dependencies: aiming for zero new runtime deps, in the spirit of prometheus-metrics-exporter-httpserver. Open questions below.
• Integration tests against Prometheus and API-compatible backends (VictoriaMetrics, Mimir, Thanos) via testcontainers, since compatibility differences are exactly where hand-rolled clients break.

Open questions

1. Minimum JDK for the module: java.net.http.HttpClient needs 11+; if the module must stay on 8, HttpURLConnection.
2. JSON parsing without adding a dependency to the BOM: a minimal internal parser vs an optional -jackson binding module.
3. Module naming: prometheus-metrics-api-client vs something clearer about direction (prometheus-query-client?).

Offer

I'm willing to contribute the initial implementation, tests, and docs, and to help maintain the module afterwards. Before writing code I'd like to hear whether maintainers would consider this in scope at all — and if the answer is no, whether you'd accept a documentation pointer to a community-maintained library instead, so the next person doesn't hand-roll client №351.