Skip to content

Commit

Permalink
Add Exemplar support to Metrics proto (open-telemetry#159)
Browse files Browse the repository at this point in the history 
* Add exemplars to proto

* handle just exemplars, nit fixes

* comments

* rawvalue -> exemplar, remove sample_count
  • Loading branch information
@cnnradams @bogdandrutu
cnnradams authored and bogdandrutu committed Aug 13, 2020
1 parent e53be03 commit 8ff66ad
Showing 1 changed file with 40 additions and 76 deletions.
116 changes: 40 additions & 76 deletions opentelemetry/proto/metrics/v1/metrics.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand All @@ -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()
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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;
}

0 comments on commit 8ff66ad

Please sign in to comment.