1// Copyright 2017 Google Inc. 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.api.servicecontrol.v1; 18 19option cc_enable_arenas = true; 20option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol"; 21option java_multiple_files = true; 22option java_outer_classname = "DistributionProto"; 23option java_package = "com.google.api.servicecontrol.v1"; 24 25// Distribution represents a frequency distribution of double-valued sample 26// points. It contains the size of the population of sample points plus 27// additional optional information: 28// 29// - the arithmetic mean of the samples 30// - the minimum and maximum of the samples 31// - the sum-squared-deviation of the samples, used to compute variance 32// - a histogram of the values of the sample points 33message Distribution { 34 // Describing buckets with constant width. 35 message LinearBuckets { 36 // The number of finite buckets. With the underflow and overflow buckets, 37 // the total number of buckets is `num_finite_buckets` + 2. 38 // See comments on `bucket_options` for details. 39 int32 num_finite_buckets = 1; 40 41 // The i'th linear bucket covers the interval 42 // [offset + (i-1) * width, offset + i * width) 43 // where i ranges from 1 to num_finite_buckets, inclusive. 44 // Must be strictly positive. 45 double width = 2; 46 47 // The i'th linear bucket covers the interval 48 // [offset + (i-1) * width, offset + i * width) 49 // where i ranges from 1 to num_finite_buckets, inclusive. 50 double offset = 3; 51 } 52 53 // Describing buckets with exponentially growing width. 54 message ExponentialBuckets { 55 // The number of finite buckets. With the underflow and overflow buckets, 56 // the total number of buckets is `num_finite_buckets` + 2. 57 // See comments on `bucket_options` for details. 58 int32 num_finite_buckets = 1; 59 60 // The i'th exponential bucket covers the interval 61 // [scale * growth_factor^(i-1), scale * growth_factor^i) 62 // where i ranges from 1 to num_finite_buckets inclusive. 63 // Must be larger than 1.0. 64 double growth_factor = 2; 65 66 // The i'th exponential bucket covers the interval 67 // [scale * growth_factor^(i-1), scale * growth_factor^i) 68 // where i ranges from 1 to num_finite_buckets inclusive. 69 // Must be > 0. 70 double scale = 3; 71 } 72 73 // Describing buckets with arbitrary user-provided width. 74 message ExplicitBuckets { 75 // 'bound' is a list of strictly increasing boundaries between 76 // buckets. Note that a list of length N-1 defines N buckets because 77 // of fenceposting. See comments on `bucket_options` for details. 78 // 79 // The i'th finite bucket covers the interval 80 // [bound[i-1], bound[i]) 81 // where i ranges from 1 to bound_size() - 1. Note that there are no 82 // finite buckets at all if 'bound' only contains a single element; in 83 // that special case the single bound defines the boundary between the 84 // underflow and overflow buckets. 85 // 86 // bucket number lower bound upper bound 87 // i == 0 (underflow) -inf bound[i] 88 // 0 < i < bound_size() bound[i-1] bound[i] 89 // i == bound_size() (overflow) bound[i-1] +inf 90 repeated double bounds = 1; 91 } 92 93 // The total number of samples in the distribution. Must be >= 0. 94 int64 count = 1; 95 96 // The arithmetic mean of the samples in the distribution. If `count` is 97 // zero then this field must be zero. 98 double mean = 2; 99 100 // The minimum of the population of values. Ignored if `count` is zero. 101 double minimum = 3; 102 103 // The maximum of the population of values. Ignored if `count` is zero. 104 double maximum = 4; 105 106 // The sum of squared deviations from the mean: 107 // Sum[i=1..count]((x_i - mean)^2) 108 // where each x_i is a sample values. If `count` is zero then this field 109 // must be zero, otherwise validation of the request fails. 110 double sum_of_squared_deviation = 5; 111 112 // The number of samples in each histogram bucket. `bucket_counts` are 113 // optional. If present, they must sum to the `count` value. 114 // 115 // The buckets are defined below in `bucket_option`. There are N buckets. 116 // `bucket_counts[0]` is the number of samples in the underflow bucket. 117 // `bucket_counts[1]` to `bucket_counts[N-1]` are the numbers of samples 118 // in each of the finite buckets. And `bucket_counts[N] is the number 119 // of samples in the overflow bucket. See the comments of `bucket_option` 120 // below for more details. 121 // 122 // Any suffix of trailing zeros may be omitted. 123 repeated int64 bucket_counts = 6; 124 125 // Defines the buckets in the histogram. `bucket_option` and `bucket_counts` 126 // must be both set, or both unset. 127 // 128 // Buckets are numbered in the range of [0, N], with a total of N+1 buckets. 129 // There must be at least two buckets (a single-bucket histogram gives 130 // no information that isn't already provided by `count`). 131 // 132 // The first bucket is the underflow bucket which has a lower bound 133 // of -inf. The last bucket is the overflow bucket which has an 134 // upper bound of +inf. All other buckets (if any) are called "finite" 135 // buckets because they have finite lower and upper bounds. As described 136 // below, there are three ways to define the finite buckets. 137 // 138 // (1) Buckets with constant width. 139 // (2) Buckets with exponentially growing widths. 140 // (3) Buckets with arbitrary user-provided widths. 141 // 142 // In all cases, the buckets cover the entire real number line (-inf, 143 // +inf). Bucket upper bounds are exclusive and lower bounds are 144 // inclusive. The upper bound of the underflow bucket is equal to the 145 // lower bound of the smallest finite bucket; the lower bound of the 146 // overflow bucket is equal to the upper bound of the largest finite 147 // bucket. 148 oneof bucket_option { 149 // Buckets with constant width. 150 LinearBuckets linear_buckets = 7; 151 152 // Buckets with exponentially growing width. 153 ExponentialBuckets exponential_buckets = 8; 154 155 // Buckets with arbitrary user-provided width. 156 ExplicitBuckets explicit_buckets = 9; 157 } 158} 159