Add detail about explicit histogram buckets and boundaries (open-tele…

…metry#1933) * Add detail about explicit histogram buckets and boundaries * reword bucket counts * nit Co-authored-by: Josh Suereth <[email protected]>
carlosalberto · Sep 22, 2021 · 4dbb536 · 4dbb536
1 parent cbc543c
commit 4dbb536
Showing 1 changed file with 15 additions and 0 deletions.
diff --git a/specification/metrics/datamodel.md b/specification/metrics/datamodel.md
@@ -398,6 +398,21 @@ denotes Delta temporality where accumulated event counts are reset to zero after
 and a new aggregation occurs. Cumulative, on the other hand, continues to
 aggregate events, resetting with the use of a new start time.
 
+Bucket counts are optional.  A Histogram without buckets conveys a
+population in terms of only the sum and count, and may be interpreted
+as a histogram with single bucket covering `(-Inf, +Inf)`.
+
+Bucket upper-bounds are inclusive (except for the case where the
+upper-bound is +Inf) while bucket lower-bounds are exclusive. That is,
+buckets express the number of values that are greater than their lower
+bound and less than or equal to their upper bound.  Importers and
+exporters working with OpenTelemetry Metrics data are meant to
+disregard this specification when translating to and from histogram
+formats that use inclusive lower bounds and exclusive upper bounds.
+Changing the inclusivity and exclusivity of bounds is an example of
+worst-case Histogram error; users should choose Histogram boundaries
+so that worst-case error is within their error tolerance.
+
 ### Summary (Legacy)
 
 [Summary](https://github.com/open-telemetry/opentelemetry-proto/blob/v0.9.0/opentelemetry/proto/metrics/v1/metrics.proto#L268)