Model an UpDown form of Histogram

[jmacd]

This proposal replaces #274, in an effort to model the traditional GaugeHistogram from Prometheus, also recognized as the Stackdriver instantaneous Histogram.

Related: Consider the proposal in #303 (comment), which supports adding information to declare Histograms having a monotonic Sum field. Histograms are basically a set of counters, and if the observations are non-negative values (like synchronous Counters events), the Sum is monotonic.

Now consider a new proposal for a kind of Histogram where the counters it represents are not monotonic. The mental model for this kind of histogram is one where you can Observe() values to add them to a set and then Unobserve() them to remove them from the set of measurements.

This proposal would add one bit of information to state that the Histogram Count field is non-monotonic. Note that this is not an API proposal for OTel metrics, just a data model proposal. It is helpful imagine the instruments you could use to output this kind of data. We can think of it as a bunch of UpDownCounter values, compared with the ordinary Histogram's bunch of Counter values, thus I refer to it as an UpDownHistogram.

At the API level--conceptually--this instrument would have a synchronous form just like the ordinary Histogram, but with a new method to un-observe values. It would aggregate with other Histograms of the same kind, retaining its non-monotonic count field.

The monotonicity of the Count field is independent of Temporality, although the Delta form of this kind of histogram would require negative Count support. We are trying to model something cumulative, in the Prometheus sense, but the Cumulative form of UpDownHistogram proposed here shares its representation with ordinary Histogram points, so it is considered potentially useful.

Like with ordinary histograms, we have not defined an asynchronous model API to produce these data points directly. In both cases, an API allowing the user to produce a histogram of values directly could be considered, but it is useful to consider how to model these asynchronous Histograms using asynchronous Counter, UpDownCounter, and Gauge instruments, with a dummy attribute to create distinct observations that is removed when aggregating into a Histogram.

The asynchronous API model Histogram based on aggregation of asynchronous Counter, UpDownCounter, and Gauge instruments may be considered useful for producing UpDownHistograms, but probably not for ordinary Histograms (because the number of observations equals the count).

[jsuereth]

@jmacd does this issue belong against the specification or the proto?

[jmacd]

I put it in the same place as #303 because it feels related. Maybe we should move it to the specification? As long as people continue to ask about GaugeHIstogram instruments and data models, I want to be sure we have some kind of issue open. This is one way to address that issue, IMO.

[jmacd]

This issue is too esoteric, it only makes sense to me.