WIP: proposal: /api/v1/info_labels endpoint for info() autocomplete#85
WIP: proposal: /api/v1/info_labels endpoint for info() autocomplete#85aknuds1 wants to merge 1 commit into
Conversation
aknuds1
force-pushed
the
arve/info-autocomplete
branch
5 times, most recently
from
476857f to
ab1b9ec
Compare
Signed-off-by: Arve Knudsen <arve.knudsen@gmail.com>
aknuds1
force-pushed
the
arve/info-autocomplete
branch
from
ab1b9ec to
6bf4a84
Compare
| | `start`, `end` | rfc3339 / unix_timestamp | No | last 1h | As per PROM-74. | | ||
| | `limit` | int ≥ 0 | No | 100, capped by `--web.search.max-limit` | Maximum number of label NAMES returned. Same `has_more` semantics as PROM-74. | | ||
| | `values_limit` | int ≥ 0 | No | 0 (no cap) | Maximum number of values returned per label. New to this endpoint. | | ||
| | `batch_size` | int > 0 | No | 100 | As per PROM-74. | |
There was a problem hiding this comment.
What does a batch size limit in this API? Label names or label values?
|
|
||
| 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). |
There was a problem hiding this comment.
This works for the existing autocomplete implementations for PromQL, why doesn't it work for the info function?
| * 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` |
There was a problem hiding this comment.
Given that this new endpoint leverages params and NDJSON from the search endpoint, perhaps this should be /api/v1/search/info_labels
There was a problem hiding this comment.
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.
| | `start`, `end` | rfc3339 / unix_timestamp | No | last 1h | As per PROM-74. | | ||
| | `limit` | int ≥ 0 | No | 100, capped by `--web.search.max-limit` | Maximum number of label NAMES returned. Same `has_more` semantics as PROM-74. | | ||
| | `values_limit` | int ≥ 0 | No | 0 (no cap) | Maximum number of values returned per label. New to this endpoint. | | ||
| | `batch_size` | int > 0 | No | 100 | As per PROM-74. | |
There was a problem hiding this comment.
Note that I believe we added a max batch size ceiling. 10,000?
|
|
||
| ### 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Thanks for the feedback @tcp13equals2, will consider.
3 participants
Add a proposal for a new
/api/v1/info_labelsendpoint for PromQL info() function autocomplete.