Skip to content

Commit

Permalink
Base-2 exponential histogram protocol support (#322)
Browse files Browse the repository at this point in the history 
* Draft base-2 exponential histogram proto

* update exemplars number

* two clarifications; unrestrict scale

* from feedback; remove sparse encoding; remove zero tolerance; keep exclusive lower bound

* add flags

* reformat

* renumber

* Rename histogram span to Buckets

* add to the Metric oneof

* Feedback applied.

* update count field comment

* reorder top-level points; use 10

* detailed->detiled
  • Loading branch information
@jmacd
jmacd authored Sep 17, 2021
1 parent 38b5b9b commit 4f5d71f
Show file tree
Hide file tree
Showing 2 changed files with 118 additions and 8 deletions.
2 changes: 1 addition & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Full list of differences found in [this compare.](https://github.com/open-teleme

### Added

* Remove if no changes for this section before release.
* ExponentialHistogram is a base-2 exponential histogram described in [OTEP 149](https://github.com/open-telemetry/oteps/pull/149).

### Removed

Expand Down
124 changes: 117 additions & 7 deletions opentelemetry/proto/metrics/v1/metrics.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -176,6 +176,7 @@ message Metric {
// This field will be removed in ~3 months, on July 1, 2021.
IntHistogram int_histogram = 8 [deprecated = true];
Histogram histogram = 9;
ExponentialHistogram exponential_histogram = 10;
Summary summary = 11;
}
}
Expand Down Expand Up @@ -216,6 +217,16 @@ message Histogram {
AggregationTemporality aggregation_temporality = 2;
}

// ExponentialHistogram represents the type of a metric that is calculated by aggregating
// as a ExponentialHistogram of all reported double measurements over a time interval.
message ExponentialHistogram {
repeated ExponentialHistogramDataPoint 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;
}

// Summary metric data are used to convey quantile summaries,
// a Prometheus (see: https://prometheus.io/docs/concepts/metric_types/#summary)
// and OpenMetrics (see: https://github.com/OpenObservability/OpenMetrics/blob/4dbf6075567ab43296eed941037c12951faafb92/protos/prometheus.proto#L45)
Expand Down Expand Up @@ -333,7 +344,7 @@ message NumberDataPoint {
repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1 [deprecated = true];

// StartTimeUnixNano is optional but strongly encouraged, see the
// the detiled comments above Metric.
// the detailed comments above Metric.
//
// Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
// 1970.
Expand Down Expand Up @@ -387,7 +398,7 @@ message HistogramDataPoint {
repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1 [deprecated = true];

// StartTimeUnixNano is optional but strongly encouraged, see the
// the detiled comments above Metric.
// the detailed comments above Metric.
//
// Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
// 1970.
Expand All @@ -405,8 +416,7 @@ message HistogramDataPoint {
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.
// must be zero.
//
// Note: Sum should only be filled out when measuring non-negative discrete
// events, and is assumed to be monotonic over the values of these events.
Expand Down Expand Up @@ -448,6 +458,106 @@ message HistogramDataPoint {
uint32 flags = 10;
}

// ExponentialHistogramDataPoint is a single data point in a timeseries that describes the
// time-varying values of a ExponentialHistogram of double values. A ExponentialHistogram contains
// summary statistics for a population of values, it may optionally contain the
// distribution of those values across a set of buckets.
//
message ExponentialHistogramDataPoint {
// The set of key/value pairs that uniquely identify the timeseries from
// where this point belongs. The list may be empty (may contain 0 elements).
repeated opentelemetry.proto.common.v1.KeyValue attributes = 1;

// StartTimeUnixNano is optional but strongly encouraged, see the
// the detailed comments above Metric.
//
// Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
// 1970.
fixed64 start_time_unix_nano = 2;

// TimeUnixNano is required, see the detailed comments above Metric.
//
// 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 "bucket_counts"
// values in the positive and negative Buckets plus the "zero_count" field.
fixed64 count = 4;

// sum of the values in the population. If count is zero then this field
// must be zero.
//
// Note: Sum should only be filled out when measuring non-negative discrete
// events, and is assumed to be monotonic over the values of these events.
// Negative events *can* be recorded, but sum should not be filled out when
// doing so. This is specifically to enforce compatibility w/ OpenMetrics,
// see: https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#histogram
double sum = 5;

// scale describes the resolution of the histogram. Boundaries are
// located at powers of the base, where:
//
// base = (2^(2^-scale))
//
// The histogram bucket identified by `index`, a signed integer,
// contains values that are greater than or equal to (base^index) and
// less than (base^(index+1)).
//
// The positive and negative ranges of the histogram are expressed
// separately. Negative values are mapped by their absolute value
// into the negative range using the same scale as the positive range.
//
// scale is not restricted by the protocol, as the permissible
// values depend on the range of the data.
sint32 scale = 6;

// zero_count is the count of values that are either exactly zero or
// within the region considered zero by the instrumentation at the
// tolerated degree of precision. This bucket stores values that
// cannot be expressed using the standard exponential formula as
// well as values that have been rounded to zero.
//
// Implementations MAY consider the zero bucket to have probability
// mass equal to (zero_count / count).
fixed64 zero_count = 7;

// positive carries the positive range of exponential bucket counts.
Buckets positive = 8;

// negative carries the negative range of exponential bucket counts.
Buckets negative = 9;

// Buckets are a set of bucket counts, encoded in a contiguous array
// of counts.
message Buckets {
// Offset is the bucket index of the first entry in the bucket_counts array.
//
// Note: This uses a varint encoding as a simple form of compression.
sint32 offset = 1;

// Count is an array of counts, where count[i] carries the count
// of the bucket at index (offset+i). count[i] is the count of
// values greater than or equal to base^(offset+i) and less than
// base^(offset+i+1).
//
// Note: By contrast, the explicit HistogramDataPoint uses
// fixed64. This field is expected to have many buckets,
// especially zeros, so uint64 has been selected to ensure
// varint encoding.
repeated uint64 bucket_counts = 2;
}

// Flags that apply to this specific data point. See DataPointFlags
// for the available flags and their meaning.
uint32 flags = 10;

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

// SummaryDataPoint is a single data point in a timeseries that describes the
// time-varying values of a Summary metric.
message SummaryDataPoint {
Expand All @@ -466,7 +576,7 @@ message SummaryDataPoint {
repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1 [deprecated = true];

// StartTimeUnixNano is optional but strongly encouraged, see the
// the detiled comments above Metric.
// the detailed comments above Metric.
//
// Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
// 1970.
Expand Down Expand Up @@ -577,7 +687,7 @@ message IntDataPoint {
repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1;

// StartTimeUnixNano is optional but strongly encouraged, see the
// the detiled comments above Metric.
// the detailed comments above Metric.
//
// Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
// 1970.
Expand Down Expand Up @@ -626,7 +736,7 @@ message IntHistogramDataPoint {
repeated opentelemetry.proto.common.v1.StringKeyValue labels = 1;

// StartTimeUnixNano is optional but strongly encouraged, see the
// the detiled comments above Metric.
// the detailed comments above Metric.
//
// Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January
// 1970.
Expand Down

0 comments on commit 4f5d71f

Please sign in to comment.