search

prometheus / docs

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

Naming conventions: _total vs. _count #2465

Open Yogu opened 1 month ago

Yogu commented 1 month ago

The Metric and label naming documentation page states that "an accumulating count has a total as a suffix".

The Histograms and summaries best practice page however uses _count as the suffix for a counter.

Are these two recommendations not contradictory? Is the count+sum pair an exception to the general counter case, and thus warrants its own suffix? (If that's the case, it would probably make sense to mention that in the "Metric and label naming" page).

beorn7 commented 3 weeks ago

You should generally avoid naming a metric with a _count suffix. This suffix is a "magic" one that summaries and (classic) histograms auto-generate when ingested (or when represented in the text format). It's IMHO a bad practice, and native histograms avoid that.

Not sure if it is more confusing than useful to explain that on the "Metric and label naming" page.

Maybe we should just list suffixes to avoid (_count, _sum, _bucket, and also _total for non-counters). I'll change the title accordingly.

Yogu commented 2 weeks ago

Thank you for the clarification!

Good to know that _count is to be avoided outside of the histogram context. So regular gauges that tell you the current count of something (e.g. the number of busy workers, number of open tasks etc.) should just not have any suffix at all (e.g. busy_workers, open_tasks), right?

What would you use if you currently only want sum + count (because a metric for the average is enough for the moment), but might want to introduce a histogram in the future? If you start with "_sum" and "_count", you could keep using them if you switch to a histogram later. Or are there subtle differences about a "naive"/manual count metric implemented as a counter and the "_count" metric published as part of a histogram?

beorn7 commented 2 weeks ago

If you just have sum + count, I would use a summary without quantiles. That's the most canonical way of representing it. If you want a histogram later, so be it. You have to change the metric type then. (In principle, you could also create a bucket-less classic histogram, but in the future, you want native histograms anyway. Another reason to use a summary for as long as you just want sum + count.)