Add Gauge. Change Metric type to be a more detailed structure with details about the aggregation and temporality.

opentelemetry/proto/metrics/v1/metrics.proto

@@ -52,9 +52,10 @@ message InstrumentationLibraryMetrics {
 // to refer to any one of the lists of points contained in the Metric.
 //
 // - Metric is composed of a MetricDescriptor and a list of data points.
-// - MetricDescriptor contains a name, description, unit, type, and temporarility.
+// - MetricDescriptor contains a name, description, unit, and type.
 // - Points is a list of DataPoints (shown vertically).
-// - DataPoint contains timestamps, labels, and one of the possible value type fields.
+// - DataPoint contains timestamps, labels, and one of the possible value type
+//   fields.
 //
 //     Metric
 //  +----------+         +------------------------+
@@ -63,8 +64,8 @@ message InstrumentationLibraryMetrics {
 //  |          |         | description            |
 //  |          |         | unit                   |
 //  |    points|--+      | type                   |
-//  +----------+  |      | temporarility          |
-//                |      +------------------------+
+//  +----------+  |      +------------------------+
+//                |
 //                |
 //                |      +---------------------------+
 //                |      |DataPoint 1                |
@@ -98,7 +99,7 @@ message InstrumentationLibraryMetrics {
 //   set for individual points.
 // - TimeUnixNano MUST be set to:
 //   - the end of the interval (CUMULATIVE or DELTA)
-//   - the instantaneous time of the event (INSTANTANEOUS).
+//   - the instantaneous time of the event.
 message Metric {
   // metric_descriptor describes the Metric.
   MetricDescriptor metric_descriptor = 1;
@@ -124,48 +125,138 @@ message MetricDescriptor {
   // described by http://unitsofmeasure.org/ucum.html.
   string unit = 3;
 
-  // Type is the type of values a metric has.
-  enum Type {
-    // INVALID_TYPE is the default Type, it MUST not be used.
-    INVALID_TYPE = 0;
+  // MeasurementValueType determines the value type for a measurement.
+  // TODO: There is an open question about whether this should control int64 vs
+  // double for Histogram and Summary. There are good arguments on both sides of
+  // this.
+  enum MeasurementValueType {
+    // INVALID_MEASUREMENT_VALUE_TYPE is the default MeasurementValueType, it MUST not be
+    // used.
+    INVALID_MEASUREMENT_VALUE_TYPE = 0;
+    // The scalar value type is an int64.
+    INT64 = 1;
+    // The scalar value type is a floating point number.
+    DOUBLE = 2;
+  }
 
-    // INT64 values are signed 64-bit integers.
+  // TODO: Decide if support for RawMeasurements (measurements recorded using
+  // the synchronous instruments) is necessary. It can be used to delegate the
+  // aggregation from the application to the agent/collector. See
+  // https://github.com/open-telemetry/opentelemetry-specification/issues/617
+
+  // Gauge represents the type of a scalar metric that always exports the
+  // "current value" for every data point. It should be used for an "unknown"
+  // aggregation.
+  // 
+  // A Gauge does not track temporality. Given the aggregation is unknown,
+  // points cannot be combined using the same aggregation, regardless of
+  // temporality. Therefore, temporality is not included. Consequently, this
+  // also means "StartTimeUnixNano" is ignored for all data points.
+  //
+  // A Metric of this Type MUST store its values as Int64DataPoint or
+  // DoubleDataPoint.
+  message Gauge {
+    // It describes the value type of the measurement used to build this
+    // aggregation.
     //
-    // A Metric of this Type MUST store its values as Int64DataPoint.
-    INT64 = 1;
+    // Determines if the points are Int64DataPoint or DoubleDataPoint, as well
+    // as the value type of the exemplars.
+    MeasurementValueType measurement_value_type = 1;
+  }
 
-    // MONOTONIC_INT64 values are monotonically increasing signed 64-bit
-    // integers.
+  // Sum represents the type of a numeric scalar metric that is calculated as a
+  // sum of all reported measurements over a time interval.
+  //
+  // TODO: Decide if this should support only MonotonicSum
+  // https://github.com/open-telemetry/opentelemetry-specification/issues/725.
+  //
+  // A Metric of this Type MUST store its values as Int64DataPoint or
+  // DoubleDataPoint.
+  message Sum {
+    // It describes the value type of the measurement used to build this
+    // aggregation.
     //
-    // A Metric of this Type MUST store its values as Int64DataPoint.
-    MONOTONIC_INT64 = 2;
+    // Determines if the points are Int64DataPoint or DoubleDataPoint, as well
+    // as the value type of the exemplars.
+    MeasurementValueType measurement_value_type = 1;
+
+    // Temporality is the temporal quality values of a metric have.
+    Temporality temporality = 2;
+
+    // If "true" means that the sum is monotonic.
+    bool is_monotonic = 3;
+
+    // TODO: Decide if knowing that the metric values are aggregated from raw
+    // measurements is important.
+  }
 
-    // DOUBLE values are double-precision floating-point numbers.
+  // Represents the type of a metric that is calculated by aggregating as a
+  // Histogram of all reported measurements over a time interval.
+  //
+  // A Metric of this Type MUST store its values as HistogramDataPoint.
+  message Histogram {
+    // It describes the value type of the measurement used to build this
+    // aggregation.
     //
-    // A Metric of this Type MUST store its values as DoubleDataPoint.
-    DOUBLE = 3;
+    // Determines the value type of the exemplars.
+    MeasurementValueType measurement_value_type = 1;
+
+    // Temporality is the temporal quality values of a metric have.
+    Temporality temporality = 2;
 
-    // MONOTONIC_DOUBLE values are monotonically increasing double-precision
-    // floating-point numbers.
+    // TODO: Decide if knowing that the metric values are aggregated from raw
+    // measurements is important.
+
+    // TODO: Decide if knowing that the Sum is monotonic is important or not,
+    // may be derived from the buckets definition.
+  }
+
+  // Represents the type of a metric that is calculated by computing a summary
+  // of all reported measurements over a time interval.
+  //
+  // A Metric of this Type MUST store its values as SummaryDataPoint.
+  message Summary {
+    // It describes the value type of the measurement used to build this
+    // aggregation.
     //
-    // A Metric of this Type MUST store its values as DoubleDataPoint.
-    MONOTONIC_DOUBLE = 4;
-
-    // Histogram measurement.
-    // Corresponding values are stored in HistogramDataPoint.
-    HISTOGRAM = 5;
-
-    // Summary value. 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 quantiles over a sliding time
-    // window.
-    // Corresponding values are stored in SummaryDataPoint.
-    SUMMARY = 6;
+    // Determines the value type of the exemplars.
+    MeasurementValueType measurement_value_type = 1;
+
+    // Temporality is the temporal quality values of a metric have.
+    Temporality temporality = 2;
+
+    // TODO: Decide if knowing that the metric values are aggregated from raw
+    // measurements is important.
+
+    // TODO: Decide if knowing that the Sum is monotonic is important or not,
+    // may be derived from the buckets definition.
   }
 
-  // type is the type of values this metric has.
-  Type type = 4;
+  // Type determines the aggregation type (if any) of the metric, what is the
+  // reported value type for the data points, as well as the relatationship to
+  // the time interval over which they are reported.
+  //
+  // TODO: Update table after the decision on:
+  // https://github.com/open-telemetry/opentelemetry-specification/issues/731.
+  // By default, metrics recording using the OpenTelemetry API are exported as
+  // (the table does not include MeasurementValueType to avoid extra rows):
+  //
+  //   Instrument         Type
+  //   ----------------------------------------------
+  //   Counter            Sum(temporality=delta;is_monotonic=true)
+  //   UpDownCounter      Sum(temporality=delta;is_monotonic=false)
+  //   ValueRecorder      Summary(temporality=delta)
+  //   SumObserver        Sum(temporality=cumulative;is_monotonic=true)
+  //   UpDownSumObserver  Sum(temporality=cumulative;is_monotonic=false)
+  //   ValueObserver      Gauge()
+  oneof type {
+    // TODO: Determine if encoding all possible values in a uint64 bitset
+    // improves performance significantly and propose that if that is the case.
+    Gauge gauge = 4;
+    Sum sum = 5;
+    Histogram histogram = 6;
+    Summary summary = 7;
+  }
 
   // Temporality is the temporal quality values of a metric have. It
   // describes how those values relate to the time interval over which they
@@ -175,6 +266,7 @@ message MetricDescriptor {
     // used.
     INVALID_TEMPORALITY = 0;
 
+    // TODO: Re-evaluate if this is still needed.
     // INSTANTANEOUS is a metric whose values are measured at a particular
     // instant. The values are not aggregated over any time interval and are
     // unique per timestamp. As such, these metrics are not expected to have
@@ -240,9 +332,6 @@ message MetricDescriptor {
     //      t_0+1 with a value of 1.
     CUMULATIVE = 3;
   }
-
-  // temporality is the Temporality of values this metric has.
-  Temporality temporality = 5;
 }
 
 // Int64DataPoint is a single data point in a timeseries that describes the time-varying