Skip to content

Update histogram best practices and metric types documentation for native histograms#2868

Open
beorn7 wants to merge 2 commits intomainfrom
beorn7/histogram2
Open

Update histogram best practices and metric types documentation for native histograms#2868
beorn7 wants to merge 2 commits intomainfrom
beorn7/histogram2

Conversation

@beorn7
Copy link
Member

@beorn7 beorn7 commented Mar 5, 2026

Fixes #2803.

With this update, the best practices page about histograms and summaries and the concepts page about metric types finally takes native histograms into account.

While working on this, it occured to me that the best practices page about histograms and summaries would probably benefit from a more fundamental rewrite, based on the user experience of the last decade. Some of the focal points of the document seem outdated from today's perspective, while other topics might be missing. (I find the focus on Apdex score a bit weird by now, and also the detailed error analysis might not appeal to a broad audience…) However, a complete rewrite would have taken a lot of time, and I did not want to let our users wait for even longer. So I went for this incremental update – which shouldn't prevent anybody from a thorough rewrite in the future.

Note that I used this opportunity to replace the term "client library" with "instrumentation library". I always thought that "client library" is confusing as it is not implementing a client in any way. (Technically, it implements a server, of which the Prometheus "server" is the client… 🤯) Even if we accept that "Prometheus client library" just means "a library to do something that has to do with Prometheus", the title "client library" still doesn't tell us what the library is actually for. (Note that the client_golang repository not only contains an instrumentation library, but also includes an actual client library that helps you to implement clients that talk to the Prometheus HTTP API.)

@beorn7 beorn7 force-pushed the beorn7/histogram2 branch 3 times, most recently from 8ab93fc to 89b7d47 Compare March 10, 2026 18:10
@beorn7 beorn7 changed the title Revamp histogram and summaries best practices Update histogram best practices and metric types documentation for native histograms Mar 10, 2026
@beorn7 beorn7 force-pushed the beorn7/histogram2 branch 2 times, most recently from 84ebcab to 85fcce3 Compare March 10, 2026 18:24
beorn7 added 2 commits March 10, 2026 20:34
With this update, the best practices document about histogram and
summaries finally takes native histograms into account.

Signed-off-by: beorn7 <beorn@grafana.com>
Note that I used this opportunity to replace the term "client library"
with "instrumentation library". I always thought that "client library"
is confusing as it is not implementing a client in any way.
(Technically, it implements a _server_, of which the Prometheus
"server" is the client… 🤯) Even if we accept that
"Prometheus client library" just means "a library to do something that
has to do with Prometheus", the title "client library" still doesn't
tell us what the library is actually for. (Note that the client_golang
repository not only contains an instrumentation library, but also
includes an _actual_ client library that helps you to implement
clients that talk to the Prometheus HTTP API.)

Signed-off-by: beorn7 <beorn@grafana.com>
@beorn7 beorn7 force-pushed the beorn7/histogram2 branch from 85fcce3 to 6ec3723 Compare March 10, 2026 19:35
@beorn7 beorn7 marked this pull request as ready for review March 10, 2026 19:35
@beorn7 beorn7 requested a review from krajorama March 10, 2026 19:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Metric types doc section needs native histograms update

1 participant