Refine descriptions of Histogram+Summary for explicit OpenMetrics com…

…pat (#302)

* Refine descriptions of Histogram+Summary for explicit OpenMetrics compatibility

Fixes #187.

- Summary data points must record non-negative values
- Histogram sum can only be present if underlying measurements are non-negative. (Opening a bug to expand our API to allow this to present in more scenarios later)

* Update CHANGELOG.md

* Update CHANGELOG.md

Co-authored-by: Joshua MacDonald <[email protected]>

* Call out openmetrics specification

* Update metrics.proto

Co-authored-by: Bogdan Drutu <[email protected]>
Co-authored-by: Bogdan Drutu <[email protected]>
Co-authored-by: Joshua MacDonald <[email protected]>

CHANGELOG.md

@@ -8,9 +8,9 @@ Full list of differences found in [this compare.](https://github.com/open-teleme
 
 * Remove if no changes for this section before release.
 
-### Changed
+### Changed: Metrics
 
-* Remove if no changes for this section before release.
+* :stop_sign: [DATA MODEL CHANGE] Histogram/Summary sums must be monotonic counters of events (#302)
 
 ### Added
 

opentelemetry/proto/metrics/v1/metrics.proto

@@ -247,8 +247,8 @@ message IntHistogram {
   AggregationTemporality aggregation_temporality = 2;
 }
 
-// Histogram represents the type of a metric that is calculated by aggregating as a
-// Histogram of all reported double measurements over a time interval.
+// Histogram represents the type of a metric that is calculated by aggregating
+// as a Histogram of all reported double measurements over a time interval.
 message Histogram {
   repeated HistogramDataPoint data_points = 1;
 
@@ -526,6 +526,12 @@ message HistogramDataPoint {
   // sum of the values in the population. If count is zero then this field
   // must be zero. This value must be equal to the sum of the "sum" fields in
   // buckets if a histogram is provided.
+  //
+  // Note: Sum should only be filled out when measuring non-negative discrete
+  // events, and is assumed to be monotonic over the values of these events.
+  // Negative events *can* be recorded, but sum should not be filled out when
+  // doing so.  This is specifically to enforce compatibility w/ OpenMetrics,
+  // see: https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#histogram
   double sum = 5;
 
   // bucket_counts is an optional field contains the count values of histogram
@@ -593,6 +599,12 @@ message SummaryDataPoint {
 
   // sum of the values in the population. If count is zero then this field
   // must be zero.
+  //
+  // Note: Sum should only be filled out when measuring non-negative discrete
+  // events, and is assumed to be monotonic over the values of these events.
+  // Negative events *can* be recorded, but sum should not be filled out when
+  // doing so.  This is specifically to enforce compatibility w/ OpenMetrics,
+  // see: https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#summary
   double sum = 5;
 
   // Represents the value at a given quantile of a distribution.
@@ -609,6 +621,8 @@ message SummaryDataPoint {
     double quantile = 1;
 
     // The value at the given quantile of a distribution.
+    //
+    // Quantile values must NOT be negative.
     double value = 2;
   }