bazel / bazel / refs/heads/cushon-hostjdk9-4 / . / third_party / googleapis / google / api / distribution.proto

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

} |