Skip to content

Commit 7ae34aa

Browse files
bogdandrutuaabmassMrAlias
authored
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): * open-telemetry/opentelemetry-specification#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 <bogdandrutu@gmail.com> * Address feedback, added more TODOs and created issues Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com> * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Aaron Abbott <aaronabbott@google.com> * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Update opentelemetry/proto/metrics/v1/metrics.proto Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com> * Fix indentation and comment for Type Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com> Co-authored-by: Aaron Abbott <aaronabbott@google.com> Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>
1 parent dfa8c32 commit 7ae34aa

1 file changed

Lines changed: 129 additions & 40 deletions

File tree

‎opentelemetry/proto/metrics/v1/metrics.proto‎

Lines changed: 129 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -52,9 +52,10 @@ message InstrumentationLibraryMetrics {
5252
// to refer to any one of the lists of points contained in the Metric.
5353
//
5454
// - Metric is composed of a MetricDescriptor and a list of data points.
55-
// - MetricDescriptor contains a name, description, unit, type, and temporarility.
55+
// - MetricDescriptor contains a name, description, unit, and type.
5656
// - Points is a list of DataPoints (shown vertically).
57-
// - DataPoint contains timestamps, labels, and one of the possible value type fields.
57+
// - DataPoint contains timestamps, labels, and one of the possible value type
58+
// fields.
5859
//
5960
// Metric
6061
// +----------+ +------------------------+
@@ -63,8 +64,8 @@ message InstrumentationLibraryMetrics {
6364
// | | | description |
6465
// | | | unit |
6566
// | points|--+ | type |
66-
// +----------+ | | temporarility |
67-
// | +------------------------+
67+
// +----------+ | +------------------------+
68+
// |
6869
// |
6970
// | +---------------------------+
7071
// | |DataPoint 1 |
@@ -98,7 +99,7 @@ message InstrumentationLibraryMetrics {
9899
// set for individual points.
99100
// - TimeUnixNano MUST be set to:
100101
// - the end of the interval (CUMULATIVE or DELTA)
101-
// - the instantaneous time of the event (INSTANTANEOUS).
102+
// - the instantaneous time of the event.
102103
message Metric {
103104
// metric_descriptor describes the Metric.
104105
MetricDescriptor metric_descriptor = 1;
@@ -124,48 +125,138 @@ message MetricDescriptor {
124125
// described by http://unitsofmeasure.org/ucum.html.
125126
string unit = 3;
126127

127-
// Type is the type of values a metric has.
128-
enum Type {
129-
// INVALID_TYPE is the default Type, it MUST not be used.
130-
INVALID_TYPE = 0;
128+
// MeasurementValueType determines the value type for a measurement.
129+
// TODO: There is an open question about whether this should control int64 vs
130+
// double for Histogram and Summary. There are good arguments on both sides of
131+
// this.
132+
enum MeasurementValueType {
133+
// INVALID_MEASUREMENT_VALUE_TYPE is the default MeasurementValueType, it MUST not be
134+
// used.
135+
INVALID_MEASUREMENT_VALUE_TYPE = 0;
136+
// The scalar value type is an int64.
137+
INT64 = 1;
138+
// The scalar value type is a floating point number.
139+
DOUBLE = 2;
140+
}
131141

132-
// INT64 values are signed 64-bit integers.
142+
// TODO: Decide if support for RawMeasurements (measurements recorded using
143+
// the synchronous instruments) is necessary. It can be used to delegate the
144+
// aggregation from the application to the agent/collector. See
145+
// https://github.com/open-telemetry/opentelemetry-specification/issues/617
146+
147+
// Gauge represents the type of a scalar metric that always exports the
148+
// "current value" for every data point. It should be used for an "unknown"
149+
// aggregation.
150+
//
151+
// A Gauge does not track temporality. Given the aggregation is unknown,
152+
// points cannot be combined using the same aggregation, regardless of
153+
// temporality. Therefore, temporality is not included. Consequently, this
154+
// also means "StartTimeUnixNano" is ignored for all data points.
155+
//
156+
// A Metric of this Type MUST store its values as Int64DataPoint or
157+
// DoubleDataPoint.
158+
message Gauge {
159+
// It describes the value type of the measurement used to build this
160+
// aggregation.
133161
//
134-
// A Metric of this Type MUST store its values as Int64DataPoint.
135-
INT64 = 1;
162+
// Determines if the points are Int64DataPoint or DoubleDataPoint, as well
163+
// as the value type of the exemplars.
164+
MeasurementValueType measurement_value_type = 1;
165+
}
136166

137-
// MONOTONIC_INT64 values are monotonically increasing signed 64-bit
138-
// integers.
167+
// Sum represents the type of a numeric scalar metric that is calculated as a
168+
// sum of all reported measurements over a time interval.
169+
//
170+
// TODO: Decide if this should support only MonotonicSum
171+
// https://github.com/open-telemetry/opentelemetry-specification/issues/725.
172+
//
173+
// A Metric of this Type MUST store its values as Int64DataPoint or
174+
// DoubleDataPoint.
175+
message Sum {
176+
// It describes the value type of the measurement used to build this
177+
// aggregation.
139178
//
140-
// A Metric of this Type MUST store its values as Int64DataPoint.
141-
MONOTONIC_INT64 = 2;
179+
// Determines if the points are Int64DataPoint or DoubleDataPoint, as well
180+
// as the value type of the exemplars.
181+
MeasurementValueType measurement_value_type = 1;
182+
183+
// Temporality is the temporal quality values of a metric have.
184+
Temporality temporality = 2;
185+
186+
// If "true" means that the sum is monotonic.
187+
bool is_monotonic = 3;
188+
189+
// TODO: Decide if knowing that the metric values are aggregated from raw
190+
// measurements is important.
191+
}
142192

143-
// DOUBLE values are double-precision floating-point numbers.
193+
// Represents the type of a metric that is calculated by aggregating as a
194+
// Histogram of all reported measurements over a time interval.
195+
//
196+
// A Metric of this Type MUST store its values as HistogramDataPoint.
197+
message Histogram {
198+
// It describes the value type of the measurement used to build this
199+
// aggregation.
144200
//
145-
// A Metric of this Type MUST store its values as DoubleDataPoint.
146-
DOUBLE = 3;
201+
// Determines the value type of the exemplars.
202+
MeasurementValueType measurement_value_type = 1;
203+
204+
// Temporality is the temporal quality values of a metric have.
205+
Temporality temporality = 2;
147206

148-
// MONOTONIC_DOUBLE values are monotonically increasing double-precision
149-
// floating-point numbers.
207+
// TODO: Decide if knowing that the metric values are aggregated from raw
208+
// measurements is important.
209+
210+
// TODO: Decide if knowing that the Sum is monotonic is important or not,
211+
// may be derived from the buckets definition.
212+
}
213+
214+
// Represents the type of a metric that is calculated by computing a summary
215+
// of all reported measurements over a time interval.
216+
//
217+
// A Metric of this Type MUST store its values as SummaryDataPoint.
218+
message Summary {
219+
// It describes the value type of the measurement used to build this
220+
// aggregation.
150221
//
151-
// A Metric of this Type MUST store its values as DoubleDataPoint.
152-
MONOTONIC_DOUBLE = 4;
153-
154-
// Histogram measurement.
155-
// Corresponding values are stored in HistogramDataPoint.
156-
HISTOGRAM = 5;
157-
158-
// Summary value. Some frameworks implemented Histograms as a summary of observations
159-
// (usually things like request durations and response sizes). While it
160-
// also provides a total count of observations and a sum of all observed
161-
// values, it calculates configurable quantiles over a sliding time
162-
// window.
163-
// Corresponding values are stored in SummaryDataPoint.
164-
SUMMARY = 6;
222+
// Determines the value type of the exemplars.
223+
MeasurementValueType measurement_value_type = 1;
224+
225+
// Temporality is the temporal quality values of a metric have.
226+
Temporality temporality = 2;
227+
228+
// TODO: Decide if knowing that the metric values are aggregated from raw
229+
// measurements is important.
230+
231+
// TODO: Decide if knowing that the Sum is monotonic is important or not,
232+
// may be derived from the buckets definition.
165233
}
166234

167-
// type is the type of values this metric has.
168-
Type type = 4;
235+
// Type determines the aggregation type (if any) of the metric, what is the
236+
// reported value type for the data points, as well as the relatationship to
237+
// the time interval over which they are reported.
238+
//
239+
// TODO: Update table after the decision on:
240+
// https://github.com/open-telemetry/opentelemetry-specification/issues/731.
241+
// By default, metrics recording using the OpenTelemetry API are exported as
242+
// (the table does not include MeasurementValueType to avoid extra rows):
243+
//
244+
// Instrument Type
245+
// ----------------------------------------------
246+
// Counter Sum(temporality=delta;is_monotonic=true)
247+
// UpDownCounter Sum(temporality=delta;is_monotonic=false)
248+
// ValueRecorder Summary(temporality=delta)
249+
// SumObserver Sum(temporality=cumulative;is_monotonic=true)
250+
// UpDownSumObserver Sum(temporality=cumulative;is_monotonic=false)
251+
// ValueObserver Gauge()
252+
oneof type {
253+
// TODO: Determine if encoding all possible values in a uint64 bitset
254+
// improves performance significantly and propose that if that is the case.
255+
Gauge gauge = 4;
256+
Sum sum = 5;
257+
Histogram histogram = 6;
258+
Summary summary = 7;
259+
}
169260

170261
// Temporality is the temporal quality values of a metric have. It
171262
// describes how those values relate to the time interval over which they
@@ -175,6 +266,7 @@ message MetricDescriptor {
175266
// used.
176267
INVALID_TEMPORALITY = 0;
177268

269+
// TODO: Re-evaluate if this is still needed.
178270
// INSTANTANEOUS is a metric whose values are measured at a particular
179271
// instant. The values are not aggregated over any time interval and are
180272
// unique per timestamp. As such, these metrics are not expected to have
@@ -240,9 +332,6 @@ message MetricDescriptor {
240332
// t_0+1 with a value of 1.
241333
CUMULATIVE = 3;
242334
}
243-
244-
// temporality is the Temporality of values this metric has.
245-
Temporality temporality = 5;
246335
}
247336

248337
// Int64DataPoint is a single data point in a timeseries that describes the time-varying

0 commit comments

Comments
 (0)
⚡