fix(om2): histograms and negative observed values

OM1.0 required that the Sum of Histograms is not represented when there
are negative observations in a histogram.

This PR is removing this requirement in OM2.0. Due to:
The requirement was never implemented by the Go and Java instrumentation
  libraries. Enforcing it now would be breaking.
The requirement makes it impossible to implement the use case where the
user wants to measure the Sum anyway.
We already warned users in the documentation about the possibility of
Sum decreasing and not being usable for rate() 10 years ago: #43.
And native histograms will not take Sum into account when calculating
counter resets during rate() , thus this problem won't come up.

Note: this PR does not make Sum mandatory, that is a different question.

Signed-off-by: György Krajcsovits <[email protected]>

Author: krajorama

content/docs/specs/om/open_metrics_spec_2_0.md

@@ -48,6 +48,10 @@ OpenMetrics is primarily a wire format, independent of any particular transport
 
 Implementers MUST expose metrics in the OpenMetrics text format in response to a simple HTTP GET request to a documented URL for a given process or device. This endpoint SHOULD be called "/metrics". Implementers MAY also expose OpenMetrics formatted metrics in other ways, such as by regularly pushing metric sets to an operator-configured endpoint over HTTP.
 
+## Changes from version 1.0
+
+In the data model, histograms are no longer required to omit the Sum if there are negative measured event values. #2627.
+
 ### Metrics and Time Series
 
 This standard expresses all system states as numerical values; counts, current values, enumerations, and boolean states being common examples. Contrary to metrics, singular events occur at a specific time. Metrics tend to aggregate data temporally. While this can lose information, the reduction in overhead is an engineering trade-off commonly chosen in many modern monitoring systems.
@@ -220,12 +224,16 @@ Histograms measure distributions of discrete events. Common examples are the lat
 
 A Histogram MetricPoint MUST contain at least one bucket, and SHOULD contain Sum, and Created values. Every bucket MUST have a threshold and a value.
 
-Histogram MetricPoints MUST have one bucket with an +Inf threshold. Buckets MUST be cumulative. As an example for a metric representing request latency in seconds its values for buckets with thresholds 1, 2, 3, and +Inf MUST follow value_1 <= value_2 <= value_3 <= value_+Inf. If ten requests took 1 second each, the values of the 1, 2, 3, and +Inf buckets MUST equal 10.
+Histogram MetricPoints MUST have one bucket with threshold equal to +Inf. Buckets MUST be cumulative.
+As an example: for a metric representing request latency in seconds that has the following bucket thresholds: 1, 2, 3, and +Inf,
+it MUST follow that value_1 <= value_2 <= value_3 <= value_+Inf. If ten requests took 1 second each, the values of the 1, 2, 3, and +Inf buckets MUST equal 10.
+Or in other words, the count of measured event values that are >1 and <=2 is equal to value_2 - value_1.
+
+The +Inf bucket counts all requests. Bucket thresholds within a MetricPoint MUST be unique. Negative threshold buckets MAY be used. Bucket thresholds MUST NOT equal NaN.
 
-The +Inf bucket counts all requests. If present, the Sum value MUST equal the Sum of all the measured event values. Bucket thresholds within a MetricPoint MUST be unique.
+Semantically, buckets values are counters so MUST NOT be NaN or negative. Bucket values MUST be integers.
 
-Semantically, Sum, and buckets values are counters so MUST NOT be NaN or negative.
-Negative threshold buckets MAY be used, but then the Histogram MetricPoint MUST NOT contain a sum value as it would no longer be a counter semantically. Bucket thresholds MUST NOT equal NaN. Count and bucket values MUST be integers.
+If present, the Sum value MUST equal the Sum of all the measured event values. The histogram MAY count negative event values, which means that the Sum may decrease.
 
 A Histogram MetricPoint SHOULD have a Timestamp value called Created. This can help ingestors discern between new metrics and long-running ones it did not see before.