Title: Proposal: Prometheus HTTP API client module (prometheus-metrics-api-client) · Issue #2306 · prometheus/client_java · GitHub
Open Graph Title: Proposal: Prometheus HTTP API client module (prometheus-metrics-api-client) · Issue #2306 · prometheus/client_java
X Title: Proposal: Prometheus HTTP API client module (prometheus-metrics-api-client) · Issue #2306 · prometheus/client_java
Description: 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 / s...
Open Graph Description: 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...
X Description: 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...
Opengraph URL: https://github.com/prometheus/client_java/issues/2306
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Proposal: Prometheus HTTP API client module (prometheus-metrics-api-client)","articleBody":"### What\n\nA 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).\n\n### Why revisit this\n\nI'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:\n\n**1. The reference Go client already ships one.** [`client_golang/api/prometheus/v1`](https://github.com/prometheus/client_golang/tree/main/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.\n\n**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](https://github.com/linkedin/cruise-control/tree/main/cruise-control/src/main/java/com/linkedin/kafka/cruisecontrol/monitor/sampling/prometheus), Spinnaker [Kayenta](https://github.com/spinnaker/kayenta/blob/master/kayenta-prometheus/src/main/java/com/netflix/kayenta/prometheus/service/PrometheusRemoteService.java), [OpenSearch SQL](https://github.com/opensearch-project/sql/blob/main/direct-query-core/src/main/java/org/opensearch/sql/prometheus/client/PrometheusClientImpl.java), [YugabyteDB](https://github.com/yugabyte/yugabyte-db/blob/master/managed/src/main/java/com/yugabyte/yw/metrics/MetricQueryHelper.java), [Apache SeaTunnel](https://github.com/apache/seatunnel/tree/dev/seatunnel-connectors-v2/connector-prometheus/src/main/java/org/apache/seatunnel/connectors/seatunnel/prometheus), [Kruize](https://github.com/kruize/autotune/blob/master/src/main/java/com/autotune/common/datasource/prometheus/PrometheusDataOperatorImpl.java), [DataStax Fallout](https://github.com/datastax/fallout/tree/master/src/main/java/com/datastax/fallout/components/metrics). The third-party libraries that exist are unmaintained one-person projects:\n\n- [mckang/promql_java_client](https://github.com/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.\n- [DanielMager/PrometheusQueries4J](https://github.com/DanielMager/PrometheusQueries4J) — single contributor, no commits since 2022.\n- [HolgerZhang/promql-builder](https://github.com/HolgerZhang/promql-builder) — PromQL query-string builder only, no HTTP/JSON layer.\n- …plus assorted single-author experiments ([PromQLGenerator](https://github.com/BohrX/PromQLGenerator), [PQLetta](https://github.com/byzatic/PQLetta)).\n\n**3. Hand-rolling keeps producing the same spec-compliance bugs.** Current example: [linkedin/cruise-control#2389](https://github.com/linkedin/cruise-control/issues/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.\n\n### Proposed scope (v1)\n\n- Endpoints: `query`, `query_range`, `series`, `labels`, `label/\u003cname>/values`, `metadata` — the subset that virtually every hand-rolled client reimplements; `client_golang`'s surface as the ceiling, added on demand.\n- Typed result model: vector / matrix / scalar / string; spec-compliant request encoding (plain-decimal or RFC 3339 timestamps, POST for long queries).\n- Auth: basic, bearer token, custom headers (e.g. `X-Scope-OrgID` for Mimir), TLS config.\n- Dependencies: aiming for zero new runtime deps, in the spirit of `prometheus-metrics-exporter-httpserver`. Open questions below.\n- Integration tests against Prometheus and API-compatible backends (VictoriaMetrics, Mimir, Thanos) via testcontainers, since compatibility differences are exactly where hand-rolled clients break.\n\n### Open questions\n\n1. Minimum JDK for the module: `java.net.http.HttpClient` needs 11+; if the module must stay on 8, `HttpURLConnection`.\n2. JSON parsing without adding a dependency to the BOM: a minimal internal parser vs an optional `-jackson` binding module.\n3. Module naming: `prometheus-metrics-api-client` vs something clearer about direction (`prometheus-query-client`?).\n\n### Offer\n\nI'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.\n\n","author":{"url":"https://github.com/gecube","@type":"Person","name":"gecube"},"datePublished":"2026-07-16T02:05:11Z","url":"https://github.com/prometheus/client_java/issues/2306"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:049055d0-88e5-e5e0-28b6-1094dcbee55b |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | C3E4:39495A:46BA5:62AF6:6AFBB5EA |
| html-safe-nonce | edaba3e36b5e3fcde94eb881f2ecd0ffb370ffe9d6a2d944a6c0de68068b4766 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJDM0U0OjM5NDk1QTo0NkJBNTo2MkFGNjo2QUZCQjVFQSIsInZpc2l0b3JfaWQiOiI1ODc1OTE4ODM1MDI5ODgyMzQ2IiwicmVnaW9uX2VkZ2UiOiJpYWQiLCJyZWdpb25fcmVuZGVyIjoiaWFkIn0= |
| visitor-hmac | 0837f856f83e8776c12ad95fc6fe9acb55b745f50a05b6ae460cac9b9aea3bd7 |
| hovercard-subject-tag | issue:4897991906 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/prometheus/client_java/2306/issue_layout |
| twitter:image | https://opengraph.githubassets.com/d72e0fb324a2398ab075633b5501180027c17781fe6f6a704bc7414eaf27029b/prometheus/client_java/issues/2306 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/d72e0fb324a2398ab075633b5501180027c17781fe6f6a704bc7414eaf27029b/prometheus/client_java/issues/2306 |
| og:image:alt | 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... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | gecube |
| hostname | github.com |
| expected-hostname | github.com |
| None | 2b2ef9c1578c18d8ed27027940544c958743213cf4461659f14d3ccdf51e162c |
| turbo-cache-control | no-preview |
| go-import | github.com/prometheus/client_java git https://github.com/prometheus/client_java.git |
| octolytics-dimension-user_id | 3380462 |
| octolytics-dimension-user_login | prometheus |
| octolytics-dimension-repository_id | 7997879 |
| octolytics-dimension-repository_nwo | prometheus/client_java |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 7997879 |
| octolytics-dimension-repository_network_root_nwo | prometheus/client_java |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | e4cce0e99cf61481a318ff12c2e8580153a6c7c6 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width