diff options
Diffstat (limited to 'third_party/googleapis/google/api/distribution.proto')
| -rw-r--r-- | third_party/googleapis/google/api/distribution.proto | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/third_party/googleapis/google/api/distribution.proto b/third_party/googleapis/google/api/distribution.proto new file mode 100644 index 0000000000..2861e9b6f3 --- /dev/null +++ b/third_party/googleapis/google/api/distribution.proto @@ -0,0 +1,185 @@ +// 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; +} |