Repository navigation
Proposal: Prometheus HTTP API client module (prometheus-metrics-api-client) #2306
Description
Activity
great idea - we'll discuss it in the community call tomorrow - feel free to join 😄
Reacted by George Gaál and Arnab NandyIn case you're proceeding with this, let me know I'm interested in contributing as well. @gecube @zeitlinger
in the community call yesterday this was discussed and decided this is a good addition to this library, published as a separate module.
The idea will be to try and provide parity with the existing go client.
Reacted by Arnab Nandyin the community call yesterday this was discussed and decided this is a good addition to this library, published as a separate module.
The idea will be to try and provide parity with the existing go client.
any plan for java client?
@arnabnandy7 @jaydeluca I think I would be able to provide smth on the next week, probably closer to the weekend.
Reacted by Arnab Nandy@arnabnandy7 @jaydeluca I think I would be able to provide smth on the next week, probably closer to the weekend.
Sure, please assign me if anything found suitable.
- added a commit that references this issue
on Jul 18, 2026 Hi @jaydeluca — apologies for the long pause, and thanks for bringing this to the community call.
I've put together a PoC: https://github.com/gecube/client_java/tree/api-client-module — a single commit on top of current
main, so the easiest way to look at it is the diff: main...gecube:client_java:api-client-moduleWhat's in it:
- A new module
prometheus-metrics-api-client, aiming at parity withclient_golang/api/prometheus/v1:query,query_range,series,labels/label/<name>/values,metadata,query_exemplars,rules,alerts,targets(+ target metadata),alertmanagers, thestatus/*endpoints,format_query, and health/readiness checks. Results come back as a typed model (vector / matrix / scalar / string), with a smallCompletableFuture-based wrapper for async use. - Zero new runtime dependencies: the module depends only on
prometheus-metrics-model. JSON parsing is a minimal internal parser, and transport isHttpURLConnectionbehind a pluggableHttpConnectionFactory, so it stays on the same JDK baseline as the rest of client_java (nojava.net.http). - Backend-compat tests: recorded response fixtures for Prometheus, VictoriaMetrics, Mimir, Thanos and Cortex run through a compat matrix, since compatibility quirks were a big part of the motivation. Request encoding is spec-compliant (plain-decimal timestamps), i.e. the
start=1.784144612388E9class of bug from PrometheusMetricSampler emits query timestamps in scientific notation, breaking strict Prometheus-compatible backends (VictoriaMetrics 422) cruise-control-for-kafka/cruise-control#2389 is covered by tests. - Integration tests (
integration-tests/it-api-client) running real queries against Prometheus and VictoriaMetrics, and a docs page underdocs/content/querying/.
Open to any and all criticism — naming, package layout, API shape, whether the admin/status endpoints belong in v1 scope at all. Happy to open a draft PR if that's a more convenient place to review.
If it would help to see the client used in a real project rather than in tests, I'm also happy to pick a victim and port it as a demonstration — the natural candidate is LinkedIn Cruise Control, whose hand-rolled Prometheus client is exactly what triggered this proposal.
@arnabnandy7 you mentioned you'd be interested in contributing — once the maintainers settle the direction, this splits well into independent pieces (per-backend integration coverage, auth options, docs), so there's room for more than one pair of hands.
Reacted by Arnab Nandy- A new module
Sure, once you split the PRs we can assign it.
i think the best way for this to move forward is to start by creating the infrastructure of the new module, and get the tooling and things put in place for all of that. From there we can see how we can break this into smaller pieces so that they are easier to review
Reacted by Arnab Nandy
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.