proposal: add info-metric label discovery APIs for info() autocomplete by aknuds1 · Pull Request #85 · prometheus/proposals

aknuds1 · 2026-06-02T09:48:07Z

Editors completing info(<expr>, {…}) need data-label names and values from info metrics scoped to the expression being edited. This proposal adds two dedicated Search API operations:

GET|POST /api/v1/search/info_labels searches non-identifying data-label names.
GET|POST /api/v1/search/info_label_values searches values for one exact label.

Both endpoints accept repeated full data_match[] matchers, including __name__ matchers selecting info metric families, and an optional instant-vector expr. Expression-derived storage selection follows the lookback, offset, and @ semantics of an instant info() evaluation.

The design builds on PROM-74, reusing the Search API’s storage interfaces, search, ranking, and NDJSON streaming infrastructure. Dedicated routes keep their info-specific scoping and expression-dependent time semantics explicit.

Both require search-api and promql-experimental-functions. A single per-request timeout covers expression evaluation and storage search. Requests containing expr require the same authorization as /api/v1/query.

The proposal defines result limits, expression-derived matcher bounds, fail-closed storage capability checks, and stream completion, warning, and truncation semantics. Suggestions are indexed candidates and do not guarantee a successful runtime join.

Work-in-progress implementation: prometheus/prometheus#17930.

colega · 2026-06-03T09:24:27Z

+
+Constructing the same response with the endpoints that exist today requires either fetching far more than needed or multiple round-trips per autocomplete suggestion.
+
+* **`/api/v1/labels` + per-name `/api/v1/label/{name}/values`** returns *all* labels matching a selector, including labels carried by the base metric, not just data labels on info metrics. Filtering client-side requires downloading the full universe of labels and then making one `/label/{name}/values` call per label of interest (N+1).


This works for the existing autocomplete implementations for PromQL, why doesn't it work for the info function?

Existing label search API doesn't work for info function autocomplete because it can't derive info series scope. I.e. the info function autocomplete API has to implement info semantics, in order to return data labels matching the expression.

tcp13equals2 · 2026-06-11T03:51:01Z

+* The response is NDJSON (`application/x-ndjson`) with the same batch + trailer contract as PROM-74.
+* The endpoint is dual-gated: `--enable-feature=search-api` covers the NDJSON + parsing infrastructure it reuses; `--enable-feature=promql-experimental-functions` covers the only consumer (`info()`). Either missing flag returns the standard Prometheus JSON error with `errorType: unavailable` and a flag-specific message.
+
+### `GET|POST /api/v1/info_labels`


Given that this new endpoint leverages params and NDJSON from the search endpoint, perhaps this should be /api/v1/search/info_labels

I thought about this. The (subjective) reason for not going that route was that info function autocomplete endpoint is not in the same logical family. I'm open to rethinking this, however.

After revising the proposal in the meantime, I kept these as top-level info_* endpoints. The reason being that the endpoints (now split into two) are specific to info(). Please let me know if you still think nesting them under /api/v1/search/ would be preferable.

tcp13equals2 · 2026-06-11T04:06:59Z

+
+### 1. Extend `/api/v1/search/label_names` to optionally return values per name
+
+Would collapse two endpoints into one. Rejected on cohesion grounds: PROM-74 keeps names and values in separate endpoints precisely so that each endpoint's response shape stays simple. The values payload is only useful when the names are scoped to info metrics, so the coupling does not belong on the general search endpoint.


I would not dismiss this option so quickly. Part of the reason for the search results format being objects/maps per record was so that additional data could be augmented with metric names, label names or label values.

The idea of extending the response format is noted https://github.com/prometheus/proposals/blob/main/proposals/0074-new-labels-values-api.md#extensibility-for-mimir-thanos-cortex.

This endpoint could be extended to include a "include_values=true&values_limit=10" and the values collections could be decorated into each label record.

We already have the "only useful in a certain context" problem on the metric_names endpoint. It supports the include_metadata=true to decorate in metric metadata records for each metric name. But this only can decorate metric names where we have metadata. It's acceptable that this part of the response may not be there.

Thanks for the feedback @tcp13equals2, will consider.

The proposal has been significantly revised in the meantime. Are you suggesting though to use /api/v1/search/label_names for info function autocomplete? I'm ruling that out for the reason that the autocomplete API needs info() specific semantics.

itsmylife · 2026-07-17T08:34:32Z

I've implemented a PoC in grafana-prometheus-datasource using your PoC in arve/info-autocomplete branch.

From PoC stand point it's working nicely. But we should challenge the return value data type (instead of returning all potential labels/values we might return labels and then values for the selected label. In simple terms I'd like to follow current labels and and label/<label-key>/values style. I think this'll make auto complete easier. It'll also help client to fetch less data.

aknuds1 · 2026-08-29T13:11:46Z

But we should challenge the return value data type (instead of returning all potential labels/values we might return labels and then values for the selected label.

@itsmylife This dual-endpoint scheme has been implemented. Thanks for the feedback!

tcp13equals2 · 2026-09-11T03:47:22Z

+| `start`, `end`   | rfc3339 / unix timestamp      | No       | last 1h                  | Storage search window when `expr` is absent. With `expr`, `start` must parse but is ignored for range selection and ordering validation; `end` supplies the default `time`.                      |
+| `search[]`       | []string                      | No       |                          | At most 32 search terms, matched against names or values according to the endpoint. Multiple terms have OR semantics.                                                                            |
+| `fuzz_threshold` | int [0..100]                  | No       | 0                        | Fuzzy threshold, as in PROM-74.                                                                                                                                                                  |
+| `fuzz_alg`       | `jarowinkler` / `subsequence` | No       | `jarowinkler`            | Fuzzy algorithm, as in PROM-74.                                                                                                                                                                  |


subsequence is the default in the Prometheus implementation.

This should now be fixed - PTAL @tcp13equals2.

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

Document the request profiles and client requirements learned from the Grafana info() autocomplete proof of concept. Clarify expression interpolation, response bounds, and terminal NDJSON handling. Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

roidelapluie · 2026-09-16T13:52:44Z

I would keep the endpoint behind /search. /search was meant partly for autocomplete, so it would be a fit. Also we could reuse some of the code and ensure some consistency between the endpoints.

I have no strong opinion about reusing endpoints with scope=info vs new endpoints. New enpoints might be easier to document and to use.

Note that we have also defined semantics that might be useful here, such as include_medatata.

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

aknuds1 · 2026-09-16T16:27:56Z

I would keep the endpoint behind /search. /search was meant partly for autocomplete, so it would be a fit.

Thanks @roidelapluie - done!

Note that we have also defined semantics that might be useful here, such as include_medatata.

Included a note on this.

aknuds1 force-pushed the arve/info-autocomplete branch 6 times, most recently from ab1b9ec to 6bf4a84 Compare June 3, 2026 09:13

colega reviewed Jun 3, 2026

View reviewed changes

Comment thread proposals/0085-info-labels-endpoint.md Outdated

colega reviewed Jun 3, 2026

View reviewed changes

tcp13equals2 reviewed Jun 11, 2026

View reviewed changes

Comment thread proposals/0085-info-labels-endpoint.md Outdated

tcp13equals2 reviewed Jun 11, 2026

View reviewed changes

itsmylife mentioned this pull request Jul 10, 2026

feat: info() data-label autocomplete via /api/v1/info_labels (PoC) grafana/grafana-prometheus-datasource#244

Closed

aknuds1 force-pushed the arve/info-autocomplete branch 2 times, most recently from 1cb8122 to 8a7dc22 Compare July 17, 2026 12:15

aknuds1 changed the title ~~WIP: proposal: /api/v1/info_labels endpoint for info() autocomplete~~ WIP: proposal: add info-metric label discovery APIs for info() autocomplete Jul 17, 2026

aknuds1 force-pushed the arve/info-autocomplete branch from 8a7dc22 to ebb9e87 Compare July 17, 2026 13:54

aknuds1 force-pushed the arve/info-autocomplete branch 2 times, most recently from 37ac590 to ab6ea6e Compare August 29, 2026 11:07

aknuds1 changed the title ~~WIP: proposal: add info-metric label discovery APIs for info() autocomplete~~ proposal: add info-metric label discovery APIs for info() autocomplete Aug 29, 2026

aknuds1 force-pushed the arve/info-autocomplete branch from ab6ea6e to 11a8be7 Compare August 29, 2026 12:24

aknuds1 mentioned this pull request Aug 29, 2026

WIP: api, web/ui: add info() data-label autocomplete prometheus/prometheus#17930

Draft

aknuds1 marked this pull request as ready for review August 29, 2026 12:50

aknuds1 added the proposal label Aug 29, 2026

aknuds1 requested review from colega, roidelapluie and tcp13equals2 and removed request for colega and tcp13equals2 August 29, 2026 13:27

aknuds1 requested review from bwplotka, colega, jesusvazquez, juliusv, krajorama and tcp13equals2 August 29, 2026 13:28

aknuds1 force-pushed the arve/info-autocomplete branch from 11a8be7 to 477232b Compare August 29, 2026 14:14

tcp13equals2 reviewed Sep 11, 2026

View reviewed changes

aknuds1 added 4 commits September 14, 2026 18:48

proposal: /api/v1/info_labels endpoint for info() autocomplete

9e981a9

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

proposal: split info label discovery endpoints

1ac8179

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

docs: align info autocomplete search defaults and examples

84ad643

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

aknuds1 force-pushed the arve/info-autocomplete branch from 477232b to 84ad643 Compare September 14, 2026 17:04

aknuds1 requested a review from tcp13equals2 September 14, 2026 17:24

docs: clarify info autocomplete discovery guarantees

12381c1

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>

docs: move info discovery endpoints under search

9c63b1e

Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>


		Constructing the same response with the endpoints that exist today requires either fetching far more than needed or multiple round-trips per autocomplete suggestion.

		* `/api/v1/labels` + per-name `/api/v1/label/{name}/values` returns all labels matching a selector, including labels carried by the base metric, not just data labels on info metrics. Filtering client-side requires downloading the full universe of labels and then making one `/label/{name}/values` call per label of interest (N+1).


		### 1. Extend `/api/v1/search/label_names` to optionally return values per name

		Would collapse two endpoints into one. Rejected on cohesion grounds: PROM-74 keeps names and values in separate endpoints precisely so that each endpoint's response shape stays simple. The values payload is only useful when the names are scoped to info metrics, so the coupling does not belong on the general search endpoint.

Uh oh!

Conversation

aknuds1 commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aknuds1 Aug 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

itsmylife commented Jul 17, 2026

Uh oh!

aknuds1 commented Aug 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

roidelapluie commented Sep 16, 2026

Uh oh!

aknuds1 commented Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aknuds1 commented Jun 2, 2026 •

edited

Loading

aknuds1 Aug 29, 2026 •

edited

Loading

aknuds1 commented Sep 16, 2026 •

edited

Loading