// 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;
}