Add Exemplar support to Metrics proto (open-telemetry#159)

* Add exemplars to proto

* handle just exemplars, nit fixes

* comments

* rawvalue -> exemplar, remove sample_count

Author: cnnradams

opentelemetry/proto/metrics/v1/metrics.proto

@@ -44,6 +44,33 @@ message InstrumentationLibraryMetrics {
   repeated Metric metrics = 2;
 }
 
+// A representation of an exemplar, which is a sample input measurement.
+// Exemplars also hold information about the environment when the measurement was recorded,
+// for example the span and trace ID of the active span when the exemplar was recorded.
+message Exemplar {
+  // The set of labels that were dropped by the aggregator, but recorded
+  // alongside the original measurement. Only labels that were dropped by the aggregator should be included
+  repeated opentelemetry.proto.common.v1.StringKeyValue dropped_labels = 1;
+
+  // time_unix_nano is the exact time when this exemplar was recorded
+  //
+  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
+  fixed64 time_unix_nano = 2;
+
+  // Numerical value of the measurement that was recorded. Only one of these
+  // two fields is used for the data, based on MetricDescriptor.measurement_value_type
+  double double_value = 3;
+  int64 int64_value = 4;
+
+  // (Optional) Span ID of the current trace.
+  // span_id may be missing if the measurement is not recorded inside a trace or if the trace is not sampled.
+  bytes span_id = 5;
+
+  // (Optional) Trace ID of the current trace.
+  // trace_id may be missing if the measurement is not recorded inside a trace or if the trace is not sampled.
+  bytes trace_id = 6;
+}
+
 // Defines a Metric which has one or more timeseries.
 //
 // The data model and relation between entities is shown in the
@@ -110,7 +137,6 @@ message Metric {
   repeated Int64DataPoint int64_data_points = 2;
   repeated DoubleDataPoint double_data_points = 3;
   repeated HistogramDataPoint histogram_data_points = 4;
-  repeated SummaryDataPoint summary_data_points = 5;
 }
 
 // Defines a metric type and its schema.
@@ -127,8 +153,7 @@ message MetricDescriptor {
 
   // 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.
+  // double for Histogram. There are good arguments on both sides of this.
   enum MeasurementValueType {
     // UNSPECIFIED is the default MeasurementValueType, it MUST not be
     // used.
@@ -206,22 +231,6 @@ message MetricDescriptor {
     AggregationTemporality aggregation_temporality = 2;
   }
 
-  // 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.
-    //
-    // Determines the value type of the exemplars.
-    MeasurementValueType measurement_value_type = 1;
-
-    // aggregation_temporality describes if the aggregator reports delta changes
-    // since last report time, or cumulative changes since a fixed start time.
-    AggregationTemporality aggregation_temporality = 2;
-  }
-
   // 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.
@@ -235,7 +244,7 @@ message MetricDescriptor {
   //   ----------------------------------------------
   //   Counter            Sum(aggregation_temporality=delta;is_monotonic=true)
   //   UpDownCounter      Sum(aggregation_temporality=delta;is_monotonic=false)
-  //   ValueRecorder      Summary(aggregation_temporality=delta)
+  //   ValueRecorder      TBD
   //   SumObserver        Sum(aggregation_temporality=cumulative;is_monotonic=true)
   //   UpDownSumObserver  Sum(aggregation_temporality=cumulative;is_monotonic=false)
   //   ValueObserver      Gauge()
@@ -245,7 +254,6 @@ message MetricDescriptor {
     Gauge gauge = 4;
     Sum sum = 5;
     Histogram histogram = 6;
-    Summary summary = 7;
   }
 
   // AggregationTemporality defines how a metric aggregator reports aggregated
@@ -348,6 +356,10 @@ message Int64DataPoint {
 
   // value itself.
   int64 value = 4;
+
+  // (Optional) List of exemplars collected from
+  // measurements that were used to form the data point
+  repeated Exemplar exemplars = 5;
 }
 
 // DoubleDataPoint is a single data point in a timeseries that describes the time-varying
@@ -378,6 +390,10 @@ message DoubleDataPoint {
 
   // value itself.
   double value = 4;
+
+  // (Optional) List of exemplars collected from
+  // measurements that were used to form the data point
+  repeated Exemplar exemplars = 5;
 }
 
 // HistogramDataPoint is a single data point in a timeseries that describes the time-varying
@@ -448,60 +464,8 @@ message HistogramDataPoint {
   // If we decide to also support (a, b] intervals we should add support for these by defining
   // a boolean value which decides what type of intervals to use.
   repeated double explicit_bounds = 7;
-}
-
-// SummaryDataPoint is a single data point in a timeseries that describes the time-varying
-// values of a Summary metric.
-message SummaryDataPoint {
-  // The set of labels that uniquely identify this timeseries.
-  repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1;
-
-  // start_time_unix_nano is the last time when the aggregation value was reset
-  // to "zero". For some metric types this is ignored, see MetricsDescriptor
-  // types for more details.
-  //
-  // The aggregation value is over the time interval (start_time_unix_nano,
-  // time_unix_nano].
-  // 
-  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
-  // 1970.
-  //
-  // Value of 0 indicates that the timestamp is unspecified. In that case the
-  // timestamp may be decided by the backend.
-  fixed64 start_time_unix_nano = 2;
-
-  // time_unix_nano is the moment when this aggregation value was reported.
-  // 
-  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
-  // 1970.
-  fixed64 time_unix_nano = 3;
-
-  // The total number of recorded values since start_time. Optional since
-  // some systems don't expose this.
-  uint64 count = 4;
-
-  // The total sum of recorded values since start_time. Optional since some
-  // systems don't expose this. If count is zero then this field must be zero.
-  double sum = 5;
-
-  // Represents the value at a given quantile of a distribution.
-  //
-  // To record Min and Max values following conventions are used:
-  // - The 1.0 quantile is equivalent to the maximum value observed.
-  // - The 0.0 quantile is equivalent to the minimum value observed.
-  //
-  // See the following issue for more context:
-  // https://github.com/open-telemetry/opentelemetry-proto/issues/125
-  message ValueAtQuantile {
-    // The quantile of a distribution. Must be in the interval
-    // [0.0, 1.0].
-    double quantile = 1;
-
-    // The value at the given quantile of a distribution.
-    double value = 2;
-  }
 
-  // A list of values at different quantiles of the distribution calculated
-  // from the current snapshot. The quantiles must be strictly increasing.
-  repeated ValueAtQuantile quantile_values = 6;
+  // (Optional) List of exemplars collected from
+  // measurements that were used to form the data point
+  repeated Exemplar exemplars = 8;
 }