Gauge vs Cumulative. (#65)

* Gauge vs Cumulative.

- Split TimeSeries into GaugeTimeSeries vs CumulativeTimeSeries.

- Merge GaugePoint and CumulativePoint into a single Point message
  to minimize validation.

- Remove TODO: we don't validate keys or values.

Author: g-easy

opencensus/proto/stats/metrics/metrics.proto

@@ -44,8 +44,10 @@ message Metric {
   MetricDescriptor metric_descriptor = 1;
 
   // One or more timeseries for a single metric, where each timeseries has
-  // one or more points.
-  repeated TimeSeries timeseries = 2;
+  // one or more points. The type of the timeseries must match
+  // metric_descriptor.type, so only one of the two should be populated.
+  repeated GaugeTimeSeries gauge_timeseries = 2;
+  repeated CumulativeTimeSeries cumulative_timeseries = 3;
 }
 
 // Defines a metric type and its schema.
@@ -103,31 +105,43 @@ message LabelKey {
 }
 
 // A collection of data points that describes the time-varying values
-// of a metric.
-message TimeSeries {
-  // TODO: Add restrictions for characters that can be used for keys and values.
-  // The set of label values that uniquely identify this timeseries. Apply to all
-  // points. The order of label values must match that of label keys in the
+// of a gauge metric.
+message GaugeTimeSeries {
+  // The set of label values that uniquely identify this timeseries. Applies to
+  // all points. The order of label values must match that of label keys in the
   // metric descriptor.
   repeated LabelValue label_values = 1;
 
-  // The data points of this timeseries. Point type MUST match the MetricDescriptor.type, so for
-  // a CUMULATIVE type only cumulative_points are present and for a GAUGE type only gauge_points
-  // are present.
-  repeated GaugePoint gauge_points = 2;
-  repeated CumulativePoint cumulative_points = 3;
+  // The data points of this timeseries. Point type MUST match the MetricDescriptor.type.
+  repeated Point points = 2;
+}
+
+// A collection of data points that describes the time-varying values
+// of a cumulative metric.
+message CumulativeTimeSeries {
+  // The time that the cumulative value was reset to zero.
+  google.protobuf.Timestamp start_time = 1; // required
+
+  // The set of label values that uniquely identify this timeseries. Applies to
+  // all points. The order of label values must match that of label keys in the
+  // metric descriptor.
+  repeated LabelValue label_values = 2;
+
+  // The data points of this timeseries. Point type MUST match the MetricDescriptor.type.
+  repeated Point points = 3;
 }
 
 message LabelValue {
   // The value for the label.
   string value = 1;
   // If false the value field is ignored and considered not set.
+  // This is used to differentiate a missing label from an empty string.
   bool has_value = 2;
 }
 
-// An instantaneous measurement of a value.
-message GaugePoint {
-  // The moment when this gauge point was recorded.
+// A timestamped measurement.
+message Point {
+  // The moment when this point was recorded.
   google.protobuf.Timestamp timestamp = 1; // required
 
   // The actual point value.
@@ -138,35 +152,16 @@ message GaugePoint {
     // A 64-bit double-precision floating-point number.
     double double_value = 3;
 
+    // A distribution value.
+    DistributionValue distribution_value = 4;
+
     // TODO: Add support for Summary type. This is an aggregation that produces
     // percentiles directly.
     //
     // See also: https://prometheus.io/docs/concepts/metric_types/#summary
   }
 }
 
-// Measurements accumulated over a time interval.
-message CumulativePoint {
-  // This must be the same until an event resets the cumulative value to zero
-  // and sets a new start for the following points.
-  google.protobuf.Timestamp start_time = 1; // required
-
-  // The end timestamp of the accumulated measurement.
-  google.protobuf.Timestamp end_time = 2; // required
-
-  // The actual point value.
-  oneof value {
-    // A 64-bit integer.
-    int64 int64_value = 3;
-
-    // A 64-bit double-precision floating-point number.
-    double double_value = 4;
-
-    // A distribution value.
-    DistributionValue distribution_value = 5;
-  }
-}
-
 // Distribution contains summary statistics for a population of values. It
 // optionally contains a histogram representing the distribution of those
 // values across a set of buckets.