From 7ae34aaceaeb19ce6e87b2b6ddb542f0104fd72c Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Thu, 30 Jul 2020 15:17:05 -0700 Subject: [PATCH] Add Gauge. Change Metric type to be a more detailed structure with details about the aggregation and temporality. (#182) * Change Metric type to be a more detailed structure with details about the aggregation and temporality. This PR takes a more descriptive approach where the Aggregation (the last applied aggregation if any) is clearly defined and Temporality is available only where it makes sense. This can help clearly identify what are the possible values and properties for different types of Aggregations. There are some things that can be considered (TODOs left in the code): * https://github.com/open-telemetry/opentelemetry-specification/issues/725 * Histogram/Summary sum - monotonicity? * Previous aggregation measurements: raw measurements or "derived" measurements (results of another aggregation). * Support for RawMeasurements (recorded via the Sync Instruments) * Decide if support for INSTANTANEOUS temporality is still needed. IMPORTANT: * This PR is not equivalent with #168 or #181, this is inspired by these PRs but makes some changes that are not compatible with that PR. * This PR is an incremental update, without any significant semantic changes (except adding the notion of GAUGE), from the current state, more changes will be added in the future to resolve the TODOs. Signed-off-by: Bogdan Drutu * Address feedback, added more TODOs and created issues Signed-off-by: Bogdan Drutu * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Aaron Abbott * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn * Fix indentation and comment for Type Signed-off-by: Bogdan Drutu Co-authored-by: Aaron Abbott Co-authored-by: Tyler Yahn --- opentelemetry/proto/metrics/v1/metrics.proto | 169 ++++++++++++++----- 1 file changed, 129 insertions(+), 40 deletions(-) diff --git a/opentelemetry/proto/metrics/v1/metrics.proto b/opentelemetry/proto/metrics/v1/metrics.proto index 66207e1a6..b990ea1dd 100644 --- a/opentelemetry/proto/metrics/v1/metrics.proto +++ b/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