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