Update histogram best practices and metric types documentation for native histograms#2868
Open
Update histogram best practices and metric types documentation for native histograms#2868
Conversation
beorn7
force-pushed
the
beorn7/histogram2
branch
3 times, most recently
from
8ab93fc to
89b7d47
Compare
beorn7
changed the title
beorn7
force-pushed
the
beorn7/histogram2
branch
3 times, most recently
from
85fcce3 to
6ec3723
Compare
krajorama
reviewed
Mar 12, 2026
docs/concepts/metric_types.md
Outdated
| @@ -51,37 +57,78 @@ Client library usage documentation for gauges: | |||
|
|
|||
| A _histogram_ samples observations (usually things like request durations or | |||
Member
There was a problem hiding this comment.
Hmm samples observations sounds like we don't take all observations into account - too similar to sampling traces. So maybe say "measures".
Member
Author
There was a problem hiding this comment.
Maybe "records"? (Note that this is about original text not affected by the NH-related update.)
beorn7
commented
Mar 18, 2026
Member
Author
beorn7
left a comment
beorn7
left a comment
There was a problem hiding this comment.
Thanks for the review. All addressed with the next push.
docs/concepts/metric_types.md
Outdated
| @@ -51,37 +57,78 @@ Client library usage documentation for gauges: | |||
|
|
|||
| A _histogram_ samples observations (usually things like request durations or | |||
Member
Author
There was a problem hiding this comment.
Maybe "records"? (Note that this is about original text not affected by the NH-related update.)
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
force-pushed
the
beorn7/histogram2
branch
from
f06c65f to
4933d05
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.)