search

prometheus / docs

Prometheus documentation: content and static site generator
https://prometheus.io
Apache License 2.0
659 stars 1.01k forks source link

Explain that `method_code:http_errors:rate5m` refers to a recording rule #1512

Closed DazWilkin closed 4 years ago

DazWilkin commented 4 years ago

The PromQL Operators documentation includes what was unfamiliar syntax to me: method_code:http_errors:rate5m.

I searched for PromQL's use of colons but found nothing obvious. I wondered whether this was mechanism for extracting field values.

It was only after some time that I discovered (and I'm still not certain) that this syntax is used by recording rules.

The documentation should not assume that its readers are approaching it sequentially and, in this case, have read preceding sections.

Although an explanation for PromQL this section does not explain that this example uses a recording rule. It would be helpful to add some form of reference to clarify that.

brian-brazil commented 4 years ago

These are valid metric names per https://prometheus.io/docs/concepts/data_model/, and PromQL reference docs are not the place to get into recording rule best practices.

As far as I can see these examples are self contained.

julnicolas commented 3 years ago

I agree wit Daz, the example from the doc is totally misleading.

Either a link to the semi-colon syntax should be provided (before the expression to prepare the reader), or the example should be replaced by an expression without colons.

When I'm looking for operator documentation I want the doc to be focused on operators. Recording rules shouldn't be part of this article at all.

sayyidyofa commented 1 year ago

2023 and the docs still obscure about this