From 8ab21e9da6246e465cd9d50d405561aedef31a1e Mon Sep 17 00:00:00 2001 From: Gianluca Date: Wed, 4 Nov 2020 18:46:42 +0000 Subject: [PATCH] =?UTF-8?q?Add=20SummaryDataPoint=20support=20to=20Metrics?= =?UTF-8?q?=20proto=20(opentelemetry/opentele=E2=80=A6=20(#227)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add SummaryDataPoint support to Metrics proto (opentelemetry/opentelemetry-specification#1146) * Add DoubleSummary to data * Add DoubleSummaryDataPoint * Comments * Update comment on opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn * Add links to Prometheus and OpenMetrics summary Co-authored-by: Bogdan Drutu Co-authored-by: Tyler Yahn --- opentelemetry/proto/metrics/v1/metrics.proto | 78 ++++++++++++++++++-- 1 file changed, 72 insertions(+), 6 deletions(-) diff --git a/opentelemetry/proto/metrics/v1/metrics.proto b/opentelemetry/proto/metrics/v1/metrics.proto index aa9d71303..08730edfc 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,16 @@ message DoubleHistogram { AggregationTemporality aggregation_temporality = 2; } +// DoubleSummary metric data are used to convey quantile summaries, +// 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; +} + // 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 +261,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 +519,61 @@ message DoubleHistogramDataPoint { repeated DoubleExemplar exemplars = 8; } +// 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. + 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 @@ -566,4 +632,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 +}