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:
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
- Minimum JDK for the module:
java.net.http.HttpClient needs 11+; if the module must stay on 8, HttpURLConnection.
- JSON parsing without adding a dependency to the BOM: a minimal internal parser vs an optional
-jackson binding module.
- 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.
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/v1providesQuery,QueryRange,Series,LabelNames,LabelValues,Metadata,Rules,Targetsand 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:Javareturns ~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: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 lenientParseFloat), 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)
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.X-Scope-OrgIDfor Mimir), TLS config.prometheus-metrics-exporter-httpserver. Open questions below.Open questions
java.net.http.HttpClientneeds 11+; if the module must stay on 8,HttpURLConnection.-jacksonbinding module.prometheus-metrics-api-clientvs 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.