This intends to avoid confusing users by the subtle difference between
a native histogram and a sparse bucket.
Signed-off-by: beorn7 <beorn@grafana.com>
This seem what OTel is converging towards, see
https://github.com/open-telemetry/oteps/pull/149 .
I see pros and cons with base-10 vs base-2. They are discussed in
detail in that OTel PR, and the gist of the discussion is pretty much
in line with my design doc. Since the balance is easy to tip here, I
think we should go with base-2 if OTel picks base-2. This also seems
to be in agreement with several proprietary solution (see again the
discussion on that OTel PR.)
The idea to make the number of buckets per power of 2 (or formerly 10)
a power of 2 itself was also sketched out in the design doc
already. It guarantees mergeability of different resolutions. I was
undecided between making it a recommendation or mandatory. Now I think
it should be mandatory as it has the additional benefit of playing
well with OTel's plans.
This commit also addresses a number of outstanding TODOs.
Signed-off-by: beorn7 <beorn@grafana.com>
This is, sadly, the only way to avoid a breaking change. The cost is
that anyone using exemplars has to perform a type assertion. This is,
however, a common pattern where interfaces turn out to need additional
methods in a stable library or only some implementations can provide
the additional methods (AKA "interface upgrade").
Needless to say that in v2 of this library, we'll do things in a more
straight forward way.
Signed-off-by: beorn7 <beorn@grafana.com>
This also updates all tests and examples to use explicitly set
objectives.
In v0.10, DefObjectives will be completely removed, and the default
Summary will have no objectives then.
Fixes#118
I intentionally left out the Makefile infrastructure that we had
previously for this, as it's not strictly needed and adds
complexity/maintenance burden.
This rewrite had may backs and forths. In my git repository, it
consists of 35 commits which I cannot group or merge into reasonable
review buckets. Gerrit breaks fundamental git semantics, so I have to
squash the 35 commits into one for the review.
I'll push this not with refs/for/master, but with refs/for/next so
that we can transition after submission in a controlled fashion.
For the review, I recommend to start with looking at godoc and in
particular the many examples. After that, continue with a line-by-line
detailed review. (The big picture is hopefully as expected after
wrapping up the discussion earlier.)
Change-Id: Ib38cc46493a5139ca29d84020650929d94cac850
Examining the existing documentation over the standard Go documentation
server revealed some serious formatting flaws. Everything should be
readable now.
- Comments are migrated from ``/* */`` to ``//`` per convention.
- ``NewDefaultHistogram`` helper.
- ``Registry.Handler`` and ``Registry.YieldExporter`` deprecation.
- Cleanup of legacy import paths.
- Updating examples to use acknowledged patterns.
- Parameterizing the random parameter namespaces for ``examples/random/main.go``, which is useful for demoing population behaviors.
1. The output format is now versioned per the Semantic Versioning scheme. Mainline Prometheus will be adapted to use differing consumption methodologies as the generators' formats evolve to support legacy clients.
2. The telemetry outputter now supports GZIP output encoding. In sample runs, this cuts the output size in half.
3. Basic sanity tests are added for registration with varying levels of pedanticness.
4. We have support for base labels in the registration and emission phases.
5. We have label support for individual metric mutation operations.
6. A number of simplications have been made.
- Provide better examples in the examples subdirectory.
- Make the comments consistent in terms of using multi-line format for future-proofing.
- Extract major constants out.
- Added normal and exponential distributions to one of the examples.
- Improved the naming of a couple of local variables.
- Handled an error in the AccumulatingBucket ValueForIndex function whereby
the vestigal old behavior was accidentally preserved and not updated.
This could have been caught had the tests been updated first.
- Simplify Histogram prospectiveIndexForPercentile such that various
small tasks it performs are extracted into separate functions for easier
testing and code comprehension.
- Remedy a regression in Histogram prospectiveIndexForPercentile whereby
the prospective index may have included the terminating element of a
bucket.
- Provide help for Histogram prospectiveIndexForPercentile such that requesting
the terminating element of a bucket will fast-forward to the first element of
the next non-empty bucket.
- Fix TallingBucket's boundary constant, because they were originally keyed toward
percentages [0, 100], not decimal-based ones. The antique tests had been
temporarily commented out, which prevented this regression from being exposed.
beorn7