legacy-libs/google-proto-files/google/api/servicecontrol/v1/distribution.proto

   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
  15 syntax = "proto3";
  16
  17 package google.api.servicecontrol.v1;
  18
  19 option cc_enable_arenas = true;
  20 option go_package = "google.golang.org/genproto/googleapis/api/servicecontrol/v1;servicecontrol";
  21 option java_multiple_files = true;
  22 option java_outer_classname = "DistributionProto";
  23 option 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
  33 message 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 }