Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add Gauge. Change Metric type to be a more detailed structure with details about the aggregation and temporality. #182

Merged
merged 9 commits into from
Jul 30, 2020
Merged

Add Gauge. Change Metric type to be a more detailed structure with details about the aggregation and temporality. #182

Changes from 3 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
f289d85
Change Metric type to be a more detailed structure with details about…
bogdandrutu Jul 21, 2020
bfccd2a
Address feedback, added more TODOs and created issues
bogdandrutu Jul 29, 2020
c2f5611
Update opentelemetry/proto/metrics/v1/metrics.proto
bogdandrutu Jul 30, 2020
7b96419
Update opentelemetry/proto/metrics/v1/metrics.proto
bogdandrutu Jul 30, 2020
f9ec68b
Update opentelemetry/proto/metrics/v1/metrics.proto
bogdandrutu Jul 30, 2020
b34be70
Update opentelemetry/proto/metrics/v1/metrics.proto
bogdandrutu Jul 30, 2020
441040a
Update opentelemetry/proto/metrics/v1/metrics.proto
bogdandrutu Jul 30, 2020
b51c65d
Update opentelemetry/proto/metrics/v1/metrics.proto
bogdandrutu Jul 30, 2020
3c8989c
Fix indentation and comment for Type
bogdandrutu Jul 30, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 128 additions & 40 deletions opentelemetry/proto/metrics/v1/metrics.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,10 @@ message InstrumentationLibraryMetrics {
// to refer to any one of the lists of points contained in the Metric.
//
// - Metric is composed of a MetricDescriptor and a list of data points.
// - MetricDescriptor contains a name, description, unit, type, and temporarility.
// - MetricDescriptor contains a name, description, unit, and type.
// - Points is a list of DataPoints (shown vertically).
// - DataPoint contains timestamps, labels, and one of the possible value type fields.
// - DataPoint contains timestamps, labels, and one of the possible value type
// fields.
//
// Metric
// +----------+ +------------------------+
Expand All @@ -63,8 +64,8 @@ message InstrumentationLibraryMetrics {
// | | | description |
// | | | unit |
// | points|--+ | type |
// +----------+ | | temporarility |
// | +------------------------+
// +----------+ | +------------------------+
// |
// |
// | +---------------------------+
// | |DataPoint 1 |
Expand Down Expand Up @@ -98,7 +99,7 @@ message InstrumentationLibraryMetrics {
// set for individual points.
// - TimeUnixNano MUST be set to:
// - the end of the interval (CUMULATIVE or DELTA)
// - the instantaneous time of the event (INSTANTANEOUS).
// - the instantaneous time of the event.
message Metric {
// metric_descriptor describes the Metric.
MetricDescriptor metric_descriptor = 1;
Expand All @@ -124,48 +125,137 @@ message MetricDescriptor {
// described by http://unitsofmeasure.org/ucum.html.
string unit = 3;

// Type is the type of values a metric has.
enum Type {
// INVALID_TYPE is the default Type, it MUST not be used.
INVALID_TYPE = 0;
// MeasurementValueType determines the value type for a measurement.
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
// 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.
enum MeasurementValueType {
// INVALID_SCALAR_VALUE_TYPE is the default ScalarValueType, it MUST not be
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
// used.
INVALID_MEASUREMENT_VALUE_TYPE = 0;
// The scalar value type is an int64.
INT64 = 1;
// The scalar value type is a floating point number.
DOUBLE = 2;
}

// INT64 values are signed 64-bit integers.
// TODO: Decide if support for RawMeasurements (measurements recorded using
// the synchronous instruments) is necessary. It can be used to delegate the
// aggregation from the application to the agent/collector. See
// https://github.com/open-telemetry/opentelemetry-specification/issues/617

// Represents the type of a scalar metric that always exports the "current
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
// value" for every data point. It can be used when an "unknown" aggregation.
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
//
// It does not contain a temporality field (even if it may be known) because
// the aggregation is unknown so points cannot be combined using the same
// aggregation to aggregate over different time window. Because of this
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
// "StartTimeUnixNano" is ignored for all data points.
//
// A Metric of this Type MUST store its values as Int64DataPoint or
// DoubleDataPoint.
message Gauge {
// It describes the value type of the measurement used to build this
// aggregation.
//
// A Metric of this Type MUST store its values as Int64DataPoint.
INT64 = 1;
// Determines if the points are Int64DataPoint or DoubleDataPoint, as well
// as the value type of the exemplars.
MeasurementValueType measurement_value_type = 1;
}

// MONOTONIC_INT64 values are monotonically increasing signed 64-bit
// integers.
// Represents the type of a numeric scalar metric that is calculated as a sum
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
// of all reported measurements over a time interval.
//
// TODO: Decide if this should support only MonotonicSum
// https://github.com/open-telemetry/opentelemetry-specification/issues/725.
//
// A Metric of this Type MUST store its values as Int64DataPoint or
// DoubleDataPoint.
message Sum {
// It describes the value type of the measurement used to build this
// aggregation.
//
// A Metric of this Type MUST store its values as Int64DataPoint.
MONOTONIC_INT64 = 2;
// Determines if the points are Int64DataPoint or DoubleDataPoint, as well
// as the value type of the exemplars.
MeasurementValueType measurement_value_type = 1;

// Temporality is the temporal quality values of a metric have.
Temporality temporality = 2;

// If "true" means that the sum is monotonic.
bool is_monotonic = 3;

// TODO: Decide if knowing that the metric values are aggregated from raw
// measurements is important.
}

// DOUBLE values are double-precision floating-point numbers.
// Represents the type of a metric that is calculated by aggregating as a
// Histogram of all reported measurements over a time interval.
//
// A Metric of this Type MUST store its values as HistogramDataPoint.
message Histogram {
// It describes the value type of the measurement used to build this
// aggregation.
//
// A Metric of this Type MUST store its values as DoubleDataPoint.
DOUBLE = 3;
// Determines the value type of the exemplars.
MeasurementValueType measurement_value_type = 1;

// Temporality is the temporal quality values of a metric have.
Temporality temporality = 2;

// MONOTONIC_DOUBLE values are monotonically increasing double-precision
// floating-point numbers.
// TODO: Decide if knowing that the metric values are aggregated from raw
// measurements is important.

// TODO: Decide if knowing that the Sum is monotonic is important or not,
// may be derived from the buckets definition.
}

// 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.
//
// A Metric of this Type MUST store its values as DoubleDataPoint.
MONOTONIC_DOUBLE = 4;

// Histogram measurement.
// Corresponding values are stored in HistogramDataPoint.
HISTOGRAM = 5;

// Summary value. Some frameworks implemented Histograms as a summary of observations
// (usually things like request durations and response sizes). While it
// also provides a total count of observations and a sum of all observed
// values, it calculates configurable quantiles over a sliding time
// window.
// Corresponding values are stored in SummaryDataPoint.
SUMMARY = 6;
// Determines the value type of the exemplars.
MeasurementValueType measurement_value_type = 1;

// Temporality is the temporal quality values of a metric have.
Temporality temporality = 2;

// TODO: Decide if knowing that the metric values are aggregated from raw
// measurements is important.

// TODO: Decide if knowing that the Sum is monotonic is important or not,
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
// may be derived from the buckets definition.
}

// type is the type of values this metric has.
Type type = 4;
// Type is the type of the metric and determines what are the type of the
MrAlias marked this conversation as resolved.
Show resolved Hide resolved
// reported value, as well as the relatationship to the time interval over
// which they are reported.
//
// TODO: Update table after the decision on:
// https://github.com/open-telemetry/opentelemetry-specification/issues/731.
// By default, metrics recording using the OpenTelemetry API are exported as
// (the table does not include MeasurementValueType to avoid extra rows):
//
// Instrument Type
// ----------------------------------------------
// Counter Sum(temporality=delta;is_monotonic=true)
// UpDownCounter Sum(temporality=delta;is_monotonic=false)
// ValueRecorder Summary(temporality=delta)
// SumObserver Sum(temporality=cumulative;is_monotonic=true)
// UpDownSumObserver Sum(temporality=cumulative;is_monotonic=false)
// ValueObserver Gauge()
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
oneof type {
// TODO: Determine if encoding all possible values in a uint64 bitset
// improves performance significantly and propose that if that is the case.
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
Gauge gauge = 4;
Sum sum = 5;
Histogram histogram = 6;
Summary summary = 7;
}

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

// TODO: Re-evaluate if this is still needed.
bogdandrutu marked this conversation as resolved.
Show resolved Hide resolved
// INSTANTANEOUS is a metric whose values are measured at a particular
// instant. The values are not aggregated over any time interval and are
// unique per timestamp. As such, these metrics are not expected to have
Expand Down Expand Up @@ -240,9 +331,6 @@ message MetricDescriptor {
// t_0+1 with a value of 1.
CUMULATIVE = 3;
}

// temporality is the Temporality of values this metric has.
Temporality temporality = 5;
}

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