Add google/api/distribution.proto

google/api/distribution.proto

@@ -0,0 +1,184 @@
+// 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 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;
+}