| // Copyright 2016 Google Inc. | |
| // | |
| // Licensed under the Apache License, Version 2.0 (the "License"); | |
| // you may not use this file except in compliance with the License. | |
| // You may obtain a copy of the License at | |
| // | |
| // http://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, software | |
| // distributed under the License is distributed on an "AS IS" BASIS, | |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| // See the License for the specific language governing permissions and | |
| // limitations under the License. | |
| syntax = "proto3"; | |
| package google.api; | |
| import "google/api/annotations.proto"; | |
| import "google/protobuf/any.proto"; | |
| import "google/protobuf/timestamp.proto"; | |
| option go_package = "google.golang.org/genproto/googleapis/api/distribution;distribution"; | |
| option java_multiple_files = true; | |
| option java_outer_classname = "DistributionProto"; | |
| option java_package = "com.google.api"; | |
| // Distribution contains summary statistics for a population of values and, | |
| // optionally, a histogram representing the distribution of those values across | |
| // a specified set of histogram buckets. | |
| // | |
| // The summary statistics are the count, mean, sum of the squared deviation from | |
| // the mean, the minimum, and the maximum of the set of population of values. | |
| // | |
| // The histogram is based on a sequence of buckets and gives a count of values | |
| // that fall into each bucket. The boundaries of the buckets are given either | |
| // explicitly or by specifying parameters for a method of computing them | |
| // (buckets of fixed width or buckets of exponentially increasing width). | |
| // | |
| // Although it is not forbidden, it is generally a bad idea to include | |
| // non-finite values (infinities or NaNs) in the population of values, as this | |
| // will render the `mean` and `sum_of_squared_deviation` fields meaningless. | |
| message Distribution { | |
| // The range of the population values. | |
| message Range { | |
| // The minimum of the population values. | |
| double min = 1; | |
| // The maximum of the population values. | |
| double max = 2; | |
| } | |
| // A Distribution may optionally contain a histogram of the values in the | |
| // population. The histogram is given in `bucket_counts` as counts of values | |
| // that fall into one of a sequence of non-overlapping buckets. The sequence | |
| // of buckets is described by `bucket_options`. | |
| // | |
| // A bucket specifies an inclusive lower bound and exclusive upper bound for | |
| // the values that are counted for that bucket. The upper bound of a bucket | |
| // is strictly greater than the lower bound. | |
| // | |
| // The sequence of N buckets for a Distribution consists of an underflow | |
| // bucket (number 0), zero or more finite buckets (number 1 through N - 2) and | |
| // an overflow bucket (number N - 1). The buckets are contiguous: the lower | |
| // bound of bucket i (i > 0) is the same as the upper bound of bucket i - 1. | |
| // The buckets span the whole range of finite values: lower bound of the | |
| // underflow bucket is -infinity and the upper bound of the overflow bucket is | |
| // +infinity. The finite buckets are so-called because both bounds are | |
| // finite. | |
| // | |
| // `BucketOptions` describes bucket boundaries in one of three ways. Two | |
| // describe the boundaries by giving parameters for a formula to generate | |
| // boundaries and one gives the bucket boundaries explicitly. | |
| // | |
| // If `bucket_boundaries` is not given, then no `bucket_counts` may be given. | |
| message BucketOptions { | |
| // Specify a sequence of buckets that all have the same width (except | |
| // overflow and underflow). Each bucket represents a constant absolute | |
| // uncertainty on the specific value in the bucket. | |
| // | |
| // Defines `num_finite_buckets + 2` (= N) buckets with these boundaries for | |
| // bucket `i`: | |
| // | |
| // Upper bound (0 <= i < N-1): offset + (width * i). | |
| // Lower bound (1 <= i < N): offset + (width * (i - 1)). | |
| message Linear { | |
| // Must be greater than 0. | |
| int32 num_finite_buckets = 1; | |
| // Must be greater than 0. | |
| double width = 2; | |
| // Lower bound of the first bucket. | |
| double offset = 3; | |
| } | |
| // Specify a sequence of buckets that have a width that is proportional to | |
| // the value of the lower bound. Each bucket represents a constant relative | |
| // uncertainty on a specific value in the bucket. | |
| // | |
| // Defines `num_finite_buckets + 2` (= N) buckets with these boundaries for | |
| // bucket i: | |
| // | |
| // Upper bound (0 <= i < N-1): scale * (growth_factor ^ i). | |
| // Lower bound (1 <= i < N): scale * (growth_factor ^ (i - 1)). | |
| message Exponential { | |
| // Must be greater than 0. | |
| int32 num_finite_buckets = 1; | |
| // Must be greater than 1. | |
| double growth_factor = 2; | |
| // Must be greater than 0. | |
| double scale = 3; | |
| } | |
| // A set of buckets with arbitrary widths. | |
| // | |
| // Defines `size(bounds) + 1` (= N) buckets with these boundaries for | |
| // bucket i: | |
| // | |
| // Upper bound (0 <= i < N-1): bounds[i] | |
| // Lower bound (1 <= i < N); bounds[i - 1] | |
| // | |
| // There must be at least one element in `bounds`. If `bounds` has only one | |
| // element, there are no finite buckets, and that single element is the | |
| // common boundary of the overflow and underflow buckets. | |
| message Explicit { | |
| // The values must be monotonically increasing. | |
| repeated double bounds = 1; | |
| } | |
| // Exactly one of these three fields must be set. | |
| oneof options { | |
| // The linear bucket. | |
| Linear linear_buckets = 1; | |
| // The exponential buckets. | |
| Exponential exponential_buckets = 2; | |
| // The explicit buckets. | |
| Explicit explicit_buckets = 3; | |
| } | |
| } | |
| // The number of values in the population. Must be non-negative. | |
| int64 count = 1; | |
| // The arithmetic mean of the values in the population. If `count` is zero | |
| // then this field must be zero. | |
| double mean = 2; | |
| // The sum of squared deviations from the mean of the values in the | |
| // population. For values x_i this is: | |
| // | |
| // Sum[i=1..n]((x_i - mean)^2) | |
| // | |
| // Knuth, "The Art of Computer Programming", Vol. 2, page 323, 3rd edition | |
| // describes Welford's method for accumulating this sum in one pass. | |
| // | |
| // If `count` is zero then this field must be zero. | |
| double sum_of_squared_deviation = 3; | |
| // If specified, contains the range of the population values. The field | |
| // must not be present if the `count` is zero. | |
| Range range = 4; | |
| // Defines the histogram bucket boundaries. | |
| BucketOptions bucket_options = 6; | |
| // If `bucket_options` is given, then the sum of the values in `bucket_counts` | |
| // must equal the value in `count`. If `bucket_options` is not given, no | |
| // `bucket_counts` fields may be given. | |
| // | |
| // Bucket counts are given in order under the numbering scheme described | |
| // above (the underflow bucket has number 0; the finite buckets, if any, | |
| // have numbers 1 through N-2; the overflow bucket has number N-1). | |
| // | |
| // The size of `bucket_counts` must be no greater than N as defined in | |
| // `bucket_options`. | |
| // | |
| // Any suffix of trailing zero bucket_count fields may be omitted. | |
| repeated int64 bucket_counts = 7; | |
| } |