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

Create a oneof for Histogram buckets; add ExplicitBuckets; deprecate DoubleHistogram #272

Closed
wants to merge 12 commits into from
Closed

Create a oneof for Histogram buckets; add ExplicitBuckets; deprecate DoubleHistogram #272

Changes from 7 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
359b214
Copy DoubleHistogram to DeprecatedHistogram
jmacd Mar 4, 2021
d9f4a70
Rename DoubleHistogram->Histogram
jmacd Mar 4, 2021
615b3f3
Move boundaries and counts into ExplicitBoundaries
jmacd Mar 4, 2021
7632f9f
Typos
jmacd Mar 4, 2021
b63c77f
Deprecation
jmacd Mar 4, 2021
cb26736
Say less about histograms being mergable, that is expected but a comp…
jmacd Mar 5, 2021
491cf07
Apply suggestions from code review
jmacd Mar 8, 2021
34b245a
Typo
jmacd Mar 11, 2021
6c1a2b4
Merge branch 'main' into jmacd/histbucks
jmacd Mar 15, 2021
1fc46a9
Merge remote-tracking branch 'origin' into jmacd/histbucks
jmacd Mar 16, 2021
a7a9e02
Merge branch 'jmacd/histbucks' of github.com:jmacd/opentelemetry-prot…
jmacd Mar 16, 2021
5e22ae2
Upstream
jmacd Mar 16, 2021
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
157 changes: 127 additions & 30 deletions opentelemetry/proto/metrics/v1/metrics.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,8 +141,15 @@ message Metric {
DoubleGauge double_gauge = 5;
IntSum int_sum = 6;
DoubleSum double_sum = 7;
// IntHistogram and DoubleHistogram are DEPRECATED and will be removed soon.
// 1. Old senders and receivers that are not aware of this change will
// continue using the `int_histogram` and `double_histogram` field.
// 2. New senders, which are aware of this change MUST send only `histogram`.
// 3. New receivers, which are aware of this change MUST convert this into
// `histogram` by converting point values.
IntHistogram int_histogram = 8;
DoubleHistogram double_histogram = 9;
Histogram histogram = 12;
DoubleSummary double_summary = 11;
}
}
Expand Down Expand Up @@ -211,8 +218,8 @@ message IntHistogram {

// Represents the type of a metric that is calculated by aggregating as a
// Histogram of all reported double measurements over a time interval.
message DoubleHistogram {
repeated DoubleHistogramDataPoint data_points = 1;
message Histogram {
repeated HistogramDataPoint data_points = 1;

// aggregation_temporality describes if the aggregator reports delta changes
// since last report time, or cumulative changes since a fixed start time.
Expand Down Expand Up @@ -420,9 +427,6 @@ message IntHistogramDataPoint {
// Otherwise all option fields and "buckets" field must be omitted in which case the
// distribution of values in the histogram is unknown and only the total count and sum are known.

// explicit_bounds is the only supported bucket option currently.
// TODO: Add more bucket options.

// explicit_bounds specifies buckets with explicitly defined bounds for values.
//
// This defines size(explicit_bounds) + 1 (= N) buckets. The boundaries for
Expand All @@ -448,7 +452,7 @@ message IntHistogramDataPoint {
// time-varying values of a Histogram of double values. A Histogram contains
// summary statistics for a population of values, it may optionally contain the
// distribution of those values across a set of buckets.
message DoubleHistogramDataPoint {
message HistogramDataPoint {
// The set of labels that uniquely identify this timeseries.
repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1;

Expand Down Expand Up @@ -482,42 +486,50 @@ message DoubleHistogramDataPoint {
// buckets if a histogram is provided.
double sum = 5;

// bucket_counts is an optional field contains the count values of histogram
// for each bucket.
//
// The sum of the bucket_counts must equal the value in the count field.
// buckets is one of several defined bucketing strategies
//
// The number of elements in bucket_counts array must be by one greater than
// the number of elements in explicit_bounds array.
repeated fixed64 bucket_counts = 6;
// If this field is omitted, there is an implied single bucket
// spanning (-Inf,+Inf) containing the whole population.
oneof buckets {
jmacd marked this conversation as resolved.
Show resolved Hide resolved
// ExplicitBuckets support encoding arbitrary boundaries and
// counts.
ExplicitBuckets explicit = 9;
}

// A histogram may optionally contain the distribution of the values in the population.
// In that case one of the option fields below and "buckets" field both must be defined.
// Otherwise all option fields and "buckets" field must be omitted in which case the
// distribution of values in the histogram is unknown and only the total count and sum are known.
// (Optional) List of exemplars collected from
// measurements that were used to form the data point
repeated DoubleExemplar exemplars = 8;
}

// explicit_bounds is the only supported bucket option currently.
// TODO: Add more bucket options.
// ExplicitBuckets is a standard way of representing arbitrary
// histogram data using explicit boundaries. It combines an
// array of N-1 boundaries and an array of N counts.
message ExplicitBuckets {
jmacd marked this conversation as resolved.
Show resolved Hide resolved
// counts is an optional field contains the count values of histogram
// for each bucket.
//
// The sum of the counts must equal the value in the HistogramDataPoint's
count field.
jmacd marked this conversation as resolved.
Show resolved Hide resolved
//
// The number of elements in counts array must be one greater than
// the number of elements in boundaries array.
repeated fixed64 counts = 6;

// explicit_bounds specifies buckets with explicitly defined bounds for values.
// boundaries specifies buckets with explicitly defined boundaries.
//
// This defines size(explicit_bounds) + 1 (= N) buckets. The boundaries for
// This defines N = size(boundaries) + 1 buckets. The boundaries for
// bucket at index i are:
//
// (-infinity, explicit_bounds[i]] for i == 0
// (explicit_bounds[i-1], explicit_bounds[i]] for 0 < i < N-1
// (explicit_bounds[i], +infinity) for i == N-1
// (-infinity, boundaries[i]] for i == 0
// (boundaries[i-1], boundaries[i]] for 0 < i < N-1
// (boundaries[i], +infinity) for i == N-1
//
// The values in the explicit_bounds array must be strictly increasing.
// The values in the boundaries array must be strictly increasing.
//
// Histogram buckets are inclusive of their upper boundary, except the last
// bucket where the boundary is at infinity. This format is intentionally
// compatible with the OpenMetrics histogram definition.
repeated double explicit_bounds = 7;

// (Optional) List of exemplars collected from
// measurements that were used to form the data point
repeated DoubleExemplar exemplars = 8;
repeated double boundaries = 7;
jmacd marked this conversation as resolved.
Show resolved Hide resolved
}

// DoubleSummaryDataPoint is a single data point in a timeseries that describes the
Expand Down Expand Up @@ -634,3 +646,88 @@ message DoubleExemplar {
// or if the trace is not sampled.
bytes trace_id = 5;
}

// DoubleHistogram is DEPRECATED.
// Represents the type of a metric that is calculated by aggregating as a
// Histogram of all reported double measurements over a time interval.
message DoubleHistogram {
repeated DoubleHistogramDataPoint data_points = 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;
}

// DoubleHistogramDataPoint is DEPRECATED.
// Represents a single data point in a timeseries that describes the
// time-varying values of a Histogram of double values. A Histogram contains
// summary statistics for a population of values, it may optionally contain the
// distribution of those values across a set of buckets.
message DoubleHistogramDataPoint {
// 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. This
// value must be equal to the sum of the "count" fields in buckets if a
// histogram is provided.
fixed64 count = 4;

// sum of the values in the population. If count is zero then this field
// must be zero. This value must be equal to the sum of the "sum" fields in
// buckets if a histogram is provided.
double sum = 5;

// bucket_counts is an optional field contains the count values of histogram
// for each bucket.
//
// The sum of the bucket_counts must equal the value in the count field.
//
// The number of elements in bucket_counts array must be by one greater than
// the number of elements in explicit_bounds array.
repeated fixed64 bucket_counts = 6;

// A histogram may optionally contain the distribution of the values in the population.
// In that case one of the option fields below and "buckets" field both must be defined.
// Otherwise all option fields and "buckets" field must be omitted in which case the
// distribution of values in the histogram is unknown and only the total count and sum are known.

// explicit_bounds specifies buckets with explicitly defined bounds for values.
//
// This defines size(explicit_bounds) + 1 (= N) buckets. The boundaries for
// bucket at index i are:
//
// (-infinity, explicit_bounds[i]] for i == 0
// (explicit_bounds[i-1], explicit_bounds[i]] for 0 < i < N-1
// (explicit_bounds[i], +infinity) for i == N-1
//
// The values in the explicit_bounds array must be strictly increasing.
//
// Histogram buckets are inclusive of their upper boundary, except the last
// bucket where the boundary is at infinity. This format is intentionally
// compatible with the OpenMetrics histogram definition.
repeated double explicit_bounds = 7;

// (Optional) List of exemplars collected from
// measurements that were used to form the data point
repeated DoubleExemplar exemplars = 8;
}