Change histogram buckets definition to be OpenMetrics compatible. (#121)

* Change histogram buckets definition to be OpenMetrics compatible.

* Improve comments.

* Use strictly increasing.

* Spelling mistake.

src/opencensus/proto/metrics/v1/metrics.proto

@@ -36,12 +36,12 @@ message Metric {
   // size, from data-model perspective a Metric contains always a
   // MetricDescriptor.
   oneof descriptor {
-    // In case of a stream reporting request can be sent only the first time
-    // a metric is reported to save network traffic.
+    // In case of a streaming RPC can be sent only the first time a metric is
+    // reported to save network traffic.
     MetricDescriptor metric_descriptor = 1;
 
-    // In case of a stream reporting request this can be sent for metrics that
-    // already sent the MetricDescriptor once.
+    // In case of a streaming RPC this can be sent for metrics that already
+    // sent the MetricDescriptor once.
     string name = 2;
   }
 
@@ -81,28 +81,30 @@ message MetricDescriptor {
     // Floating point gauge. The value can go both up and down.
     GAUGE_DOUBLE = 2;
 
-    // Distribution gauge measurement. The count can go both up and down.
+    // Distribution gauge measurement. The count and sum can go both up and
+    // down. Recorded values are always >= 0.
     // Used in scenarios like a snapshot of time the current items in a queue
     // have spent there.
     GAUGE_DISTRIBUTION = 3;
 
-    // Integer cumulative measurement. The value can only go up, if resets then
-    // the start_time should also be reset.
+    // Integer cumulative measurement. The value cannot decrease, if resets
+    // then the start_time should also be reset.
     CUMULATIVE_INT64 = 4;
 
-    // Floating point cumulative measurement. The value can only go up, if
-    // resets then the start_time should also be reset.
+    // Floating point cumulative measurement. The value cannot decrease, if
+    // resets then the start_time should also be reset. Recorded values are
+    // always >= 0.
     CUMULATIVE_DOUBLE = 5;
 
-    // Distribution cumulative measurement. The count can only go up, if resets
-    // then the start_time should also be reset.
+    // Distribution cumulative measurement. The count and sum cannot decrease,
+    // if resets then the start_time should also be reset.
     CUMULATIVE_DISTRIBUTION = 6;
 
     // Some frameworks implemented Histograms as a summary of observations
     // (usually things like request durations and response sizes). While it
     // also provides a total count of observations and a sum of all observed
-    // values, it calculates configurable percentiles over a sliding time window.
-    // This is not recommended, since it cannot be aggregated.
+    // values, it calculates configurable percentiles over a sliding time
+    // window. This is not recommended, since it cannot be aggregated.
     SUMMARY = 7;
   }
   Type type = 4;
@@ -125,7 +127,7 @@ message LabelKey {
 message TimeSeries {
   // Must be present for cumulative metrics. The time when the cumulative value
   // was reset to zero. The cumulative value is over the time interval
-  // [start_timestamp, timestamp]. If not specified, the backend can use the
+  // [start_timestamp, timestamp). If not specified, the backend can use the
   // previous recorded value.
   google.protobuf.Timestamp start_timestamp = 1;
 
@@ -195,26 +197,37 @@ message DistributionValue {
 
   // A Distribution may optionally contain a histogram of the values in the
   // population. The bucket boundaries for that histogram are described by
-  // bucket_bounds. This defines size(bucket_bounds) + 1 (= N)
-  // buckets. The boundaries for bucket index i are:
-  //
-  // (-infinity, bucket_bounds[i]) for i == 0
-  // [bucket_bounds[i-1], bucket_bounds[i]) for 0 < i < N-2
-  // [bucket_bounds[i-1], +infinity) for i == N-1
+  // BucketOptions.
   //
-  // i.e. an underflow bucket (number 0), zero or more finite buckets (1
-  // through N - 2, and an overflow bucket (N - 1), with inclusive lower
-  // bounds and exclusive upper bounds.
-  //
-  // If bucket_bounds has no elements (zero size), then there is no
-  // histogram associated with the Distribution. If bucket_bounds has only
-  // one element, there are no finite buckets, and that single element is the
-  // common boundary of the overflow and underflow buckets. The values must
-  // be monotonically increasing.
-  //
-  // Don't change bucket boundaries within a timeseries if your backend
-  // doesn't support this.
-  repeated double bucket_bounds = 4;
+  // If bucket_options has no type, then there is no histogram associated with
+  // the Distribution.
+  message BucketOptions {
+    oneof type {
+      // Bucket with explicit bounds.
+      Explicit explicit = 1;
+    }
+
+    // Specifies a set of buckets with arbitrary upper-bounds.
+    // This defines size(bounds) + 1 (= N) buckets. The boundaries for bucket
+    // index i are:
+    //
+    // [0, bucket_bounds[i]) for i == 0
+    // [bucket_bounds[i-1], bucket_bounds[i]) for 0 < i < N-1
+    // [bucket_bounds[i-1], +infinity) for i == N-1
+    message Explicit {
+      // The values must be strictly increasing and > 0.
+      repeated double bounds = 1;
+    }
+
+    // TODO: If OpenMetrics decides to support (a, b] intervals we should add
+    // support for these by defining a boolean value here which decides what
+    // type of intervals to use.
+  }
+
+  // Don't change bucket boundaries within a TimeSeries if your backend doesn't
+  // support this. To save network bandwidth this field can be sent only the
+  // first time a metric is sent when using a streaming RPC.
+  BucketOptions bucket_options = 4;
 
   message Bucket {
     // The number of values in each bucket of the histogram, as described in
@@ -280,8 +293,7 @@ message SummaryValue {
     }
 
     // A list of values at different percentiles of the distribution calculated
-    // from the current snapshot. The percentiles must be monotonically
-    // increasing.
+    // from the current snapshot. The percentiles must be strictly increasing.
     repeated ValueAtPercentile percentile_values = 3;
   }