diff --git a/src/opencensus/proto/metrics/v1/metrics.proto b/src/opencensus/proto/metrics/v1/metrics.proto index 9f1facd..54aebac 100644 --- a/src/opencensus/proto/metrics/v1/metrics.proto +++ b/src/opencensus/proto/metrics/v1/metrics.proto @@ -36,12 +36,12 @@ message Metric { // size, from data-model perspective a Metric contains always a // MetricDescriptor. oneof descriptor { - // In case of a stream reporting request can be sent only the first time - // a metric is reported to save network traffic. + // In case of a streaming RPC can be sent only the first time a metric is + // reported to save network traffic. MetricDescriptor metric_descriptor = 1; - // In case of a stream reporting request this can be sent for metrics that - // already sent the MetricDescriptor once. + // In case of a streaming RPC this can be sent for metrics that already + // sent the MetricDescriptor once. string name = 2; } @@ -81,28 +81,30 @@ message MetricDescriptor { // Floating point gauge. The value can go both up and down. GAUGE_DOUBLE = 2; - // Distribution gauge measurement. The count can go both up and down. + // Distribution gauge measurement. The count and sum can go both up and + // down. Recorded values are always >= 0. // Used in scenarios like a snapshot of time the current items in a queue // have spent there. GAUGE_DISTRIBUTION = 3; - // Integer cumulative measurement. The value can only go up, if resets then - // the start_time should also be reset. + // Integer cumulative measurement. The value cannot decrease, if resets + // then the start_time should also be reset. CUMULATIVE_INT64 = 4; - // Floating point cumulative measurement. The value can only go up, if - // resets then the start_time should also be reset. + // Floating point cumulative measurement. The value cannot decrease, if + // resets then the start_time should also be reset. Recorded values are + // always >= 0. CUMULATIVE_DOUBLE = 5; - // Distribution cumulative measurement. The count can only go up, if resets - // then the start_time should also be reset. + // Distribution cumulative measurement. The count and sum cannot decrease, + // if resets then the start_time should also be reset. CUMULATIVE_DISTRIBUTION = 6; // 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 percentiles over a sliding time window. - // This is not recommended, since it cannot be aggregated. + // values, it calculates configurable percentiles over a sliding time + // window. This is not recommended, since it cannot be aggregated. SUMMARY = 7; } Type type = 4; @@ -125,7 +127,7 @@ message LabelKey { message TimeSeries { // Must be present for cumulative metrics. The time when the cumulative value // was reset to zero. The cumulative value is over the time interval - // [start_timestamp, timestamp]. If not specified, the backend can use the + // [start_timestamp, timestamp). If not specified, the backend can use the // previous recorded value. google.protobuf.Timestamp start_timestamp = 1; @@ -195,26 +197,37 @@ message DistributionValue { // A Distribution may optionally contain a histogram of the values in the // population. The bucket boundaries for that histogram are described by - // bucket_bounds. This defines size(bucket_bounds) + 1 (= N) - // buckets. The boundaries for bucket index i are: - // - // (-infinity, bucket_bounds[i]) for i == 0 - // [bucket_bounds[i-1], bucket_bounds[i]) for 0 < i < N-2 - // [bucket_bounds[i-1], +infinity) for i == N-1 + // BucketOptions. // - // i.e. an underflow bucket (number 0), zero or more finite buckets (1 - // through N - 2, and an overflow bucket (N - 1), with inclusive lower - // bounds and exclusive upper bounds. - // - // If bucket_bounds has no elements (zero size), then there is no - // histogram associated with the Distribution. If bucket_bounds has only - // one element, there are no finite buckets, and that single element is the - // common boundary of the overflow and underflow buckets. The values must - // be monotonically increasing. - // - // Don't change bucket boundaries within a timeseries if your backend - // doesn't support this. - repeated double bucket_bounds = 4; + // If bucket_options has no type, then there is no histogram associated with + // the Distribution. + message BucketOptions { + oneof type { + // Bucket with explicit bounds. + Explicit explicit = 1; + } + + // Specifies a set of buckets with arbitrary upper-bounds. + // This defines size(bounds) + 1 (= N) buckets. The boundaries for bucket + // index i are: + // + // [0, bucket_bounds[i]) for i == 0 + // [bucket_bounds[i-1], bucket_bounds[i]) for 0 < i < N-1 + // [bucket_bounds[i-1], +infinity) for i == N-1 + message Explicit { + // The values must be strictly increasing and > 0. + repeated double bounds = 1; + } + + // TODO: If OpenMetrics decides to support (a, b] intervals we should add + // support for these by defining a boolean value here which decides what + // type of intervals to use. + } + + // Don't change bucket boundaries within a TimeSeries if your backend doesn't + // support this. To save network bandwidth this field can be sent only the + // first time a metric is sent when using a streaming RPC. + BucketOptions bucket_options = 4; message Bucket { // The number of values in each bucket of the histogram, as described in @@ -280,8 +293,7 @@ message SummaryValue { } // A list of values at different percentiles of the distribution calculated - // from the current snapshot. The percentiles must be monotonically - // increasing. + // from the current snapshot. The percentiles must be strictly increasing. repeated ValueAtPercentile percentile_values = 3; }