Reserved labels in client libraries

[Chris Sinjakli]

Hello everyone,

We've been having an interesting conversation in this issue over on client_ruby, and I wanted to double check what I found with people here.

Am I right in thinking that client libraries generally don't reserve any label names outside of ones prefixed with double underscore? I'm curious if this is something that's changed over time in other clients and we've not kept up, or if at some point we went in a different direction from the rest of the libraries.

I'm keen to match up with what we offer elsewhere.

Cheers,

Chris

[Bjoern Rabenstein]

On 08.02.23 09:50, Chris Sinjakli wrote:
>
> Am I right in thinking that client libraries generally don't reserve any
> label names outside of ones prefixed with double underscore? I'm curious if
> this is something that's changed over time in other clients and we've not
> kept up, or if at some point we went in a different direction from the rest
> of the libraries.

I don't think anything is strictly reserved. As Bryan Boreham
mentioned on the issue, Prometheus simply prefixes `instance` and
`job` with `exported_` (unless `honor_labels` is set to true), so that
is handled deliberately.

Then there are other labels that have an implied meaning in certain
contexts, like `le` for (conventional) histogram buckets or `quantile`
for pre-calculated quantiles in summaries. But again, there is no hard
rule to not use them anywhere else.

In other words: It's helpful if instrumentation libraries don't let
you use a `quantile` label on a summary or an `le` label on a
histogram, but it's totally fine to use those labels on a counter or
gauge (or `quantile` on a histogram and `le` on a summary).

--
Björn Rabenstein
[PGP-ID] 0x851C3DA17D748D03
[email] bjo...@rabenste.in

[Chris Sinjakli]

> I don't think anything is strictly reserved. As Bryan Boreham mentioned on
> the issue, Prometheus simply prefixes `instance` and `job` with `exported_`
> (unless `honor_labels` is set to true), so that is handled deliberately.

Cool, thanks for confirming. I think we have some restrictions to remove from
the Ruby client in that case.

> In other words: It's helpful if instrumentation libraries don't let you use a
> `quantile` label on a summary or an `le` label on a histogram, but it's
> totally fine to use those labels on a counter or gauge (or `quantile` on a
> histogram and `le` on a summary).

That makes sense. I just checked and we do reserve those two (`quantile` and
`le`) in the appropriate contexts.

I'm going have a quick check to make sure it doesn't break any assumptions
we've made elsewhere in the client (I'm thinking about our on-disk metric
storage for multi-process servers in particular) and then remove `instance` and
`job` from the set of reserved labels.

`pid` is going to be more complicated. Any type of metric can be configured to
report a separate value for each process in a multi-process server (gauges do
by default, but others can be confiured that way). I think we can loosen the
restriction on `pid` to be dependent on the `aggregation` specified for the
metric, but I want to be really sure I'm not introducing weird edge case bugs
by doing so.

I'm going to defer changes to `pid` to a future PR in the interest of fixing
`instance` and `job` sooner.