From ecf409d93ed71390a26f3ad9cb6d54c7b7c351cc Mon Sep 17 00:00:00 2001 From: Gianluca Cacace Date: Wed, 28 Oct 2020 12:52:18 +0000 Subject: [PATCH 1/3] Add SummaryDataPoint support to Metrics proto (opentelemetry/opentelemetry-specification#1146) * Add DoubleSummary to data * Add DoubleSummaryDataPoint * Comments --- opentelemetry/proto/metrics/v1/metrics.proto | 74 ++++++++++++++++++-- 1 file changed, 69 insertions(+), 5 deletions(-) diff --git a/opentelemetry/proto/metrics/v1/metrics.proto b/opentelemetry/proto/metrics/v1/metrics.proto index aa9d71303..0333185a4 100644 --- a/opentelemetry/proto/metrics/v1/metrics.proto +++ b/opentelemetry/proto/metrics/v1/metrics.proto @@ -61,11 +61,11 @@ message InstrumentationLibraryMetrics { // +------------+ // |name | // |description | -// |unit | +---------------------------+ -// |data |---> |Gauge, Sum, Histogram, ... | -// +------------+ +---------------------------+ +// |unit | +------------------------------------+ +// |data |---> |Gauge, Sum, Histogram, Summary, ... | +// +------------+ +------------------------------------+ // -// Data [One of Gauge, Sum, Histogram, ...] +// Data [One of Gauge, Sum, Histogram, Summary, ...] // +-----------+ // |... | // Metadata about the Data. // |points |--+ @@ -142,6 +142,7 @@ message Metric { DoubleSum double_sum = 7; IntHistogram int_histogram = 8; DoubleHistogram double_histogram = 9; + DoubleSummary double_summary = 11; } } @@ -217,6 +218,14 @@ message DoubleHistogram { AggregationTemporality aggregation_temporality = 2; } +// DoubleSummary metric data are used to convey quantile summaries, +// a Prometheus and OpenMetrics data type. These data points cannot +// always be merged in a meaningful way. While they can be useful in some +// applications, histogram data points are recommended for new applications. +message DoubleSummary { + repeated DoubleSummaryDataPoint data_points = 1; +} + // AggregationTemporality defines how a metric aggregator reports aggregated // values. It describes how those values relate to the time interval over // which they are aggregated. @@ -250,7 +259,7 @@ enum AggregationTemporality { // t_0+2 with a value of 2. AGGREGATION_TEMPORALITY_DELTA = 1; - // CUMULATIVE is an AggregationTemporality for a metic aggregator which + // CUMULATIVE is an AggregationTemporality for a metric aggregator which // reports changes since a fixed start time. This means that current values // of a CUMULATIVE metric depend on all previous measurements since the // start time. Because of this, the sender is required to retain this state @@ -508,6 +517,61 @@ message DoubleHistogramDataPoint { repeated DoubleExemplar exemplars = 8; } +// SummaryDataPoint is a single data point in a timeseries that describes the +// time-varying values of a Summary metric. +message DoubleSummaryDataPoint { + // 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 data 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; + + // count is the number of values in the population. Must be non-negative. + fixed64 count = 4; + + // sum of the values in the population. 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; + } + + // (Optional) 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; +} + // A representation of an exemplar, which is a sample input int 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 From 70c7b09f11d485909ccf25974b734a6cef376661 Mon Sep 17 00:00:00 2001 From: Gianluca Date: Wed, 4 Nov 2020 15:41:22 +0000 Subject: [PATCH 2/3] Update comment on opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn --- opentelemetry/proto/metrics/v1/metrics.proto | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/opentelemetry/proto/metrics/v1/metrics.proto b/opentelemetry/proto/metrics/v1/metrics.proto index 0333185a4..422b7405a 100644 --- a/opentelemetry/proto/metrics/v1/metrics.proto +++ b/opentelemetry/proto/metrics/v1/metrics.proto @@ -517,7 +517,7 @@ message DoubleHistogramDataPoint { repeated DoubleExemplar exemplars = 8; } -// SummaryDataPoint is a single data point in a timeseries that describes the +// DoubleSummaryDataPoint is a single data point in a timeseries that describes the // time-varying values of a Summary metric. message DoubleSummaryDataPoint { // The set of labels that uniquely identify this timeseries. @@ -630,4 +630,4 @@ message DoubleExemplar { // trace_id may be missing if the measurement is not recorded inside a trace // or if the trace is not sampled. bytes trace_id = 5; -} \ No newline at end of file +} From 73d39427ed61c51f55426bde649f9c76e452c42b Mon Sep 17 00:00:00 2001 From: Gianluca Cacace Date: Wed, 4 Nov 2020 15:54:57 +0000 Subject: [PATCH 3/3] Add links to Prometheus and OpenMetrics summary --- opentelemetry/proto/metrics/v1/metrics.proto | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/opentelemetry/proto/metrics/v1/metrics.proto b/opentelemetry/proto/metrics/v1/metrics.proto index 422b7405a..08730edfc 100644 --- a/opentelemetry/proto/metrics/v1/metrics.proto +++ b/opentelemetry/proto/metrics/v1/metrics.proto @@ -219,9 +219,11 @@ message DoubleHistogram { } // DoubleSummary metric data are used to convey quantile summaries, -// a Prometheus and OpenMetrics data type. These data points cannot -// always be merged in a meaningful way. While they can be useful in some -// applications, histogram data points are recommended for new applications. +// a Prometheus (see: https://prometheus.io/docs/concepts/metric_types/#summary) +// and OpenMetrics (see: https://github.com/OpenObservability/OpenMetrics/blob/4dbf6075567ab43296eed941037c12951faafb92/protos/prometheus.proto#L45) +// data type. These data points cannot always be merged in a meaningful way. +// While they can be useful in some applications, histogram data points are +// recommended for new applications. message DoubleSummary { repeated DoubleSummaryDataPoint data_points = 1; }