proposal: add info-metric label discovery APIs for info() autocomplete

[aknuds1]

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.

[itsmylife]

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]

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!

[roidelapluie]

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.

[aknuds1]

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.

[roidelapluie]

Approved. I’d like it to remain experimental until we have a clearer picture of performance under realistic autocomplete usage. I suggest reusing the search-api toggle, with two separate entries in /api/v1/features for general search and info-label search, so clients can distinguish support for each.

[aknuds1]

Thanks @roidelapluie!