diff --git a/opentelemetry/proto/metrics/v1/metrics.proto b/opentelemetry/proto/metrics/v1/metrics.proto index 9d84b78fc..8e4af495d 100644 --- a/opentelemetry/proto/metrics/v1/metrics.proto +++ b/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; }