diff options
author | 2016-05-23 09:14:25 -0700 | |
---|---|---|
committer | 2016-05-23 09:14:25 -0700 | |
commit | 013ea77216d2432b7a7b4fba73b5560e3d38e508 (patch) | |
tree | c63a2841154dfcb13c72385d0c46522813a9a76f /src/core/ext/census/census.proto | |
parent | 0b4d1238b8d3c7e92ae014a28f19397f38811399 (diff) |
checkpoint
Diffstat (limited to 'src/core/ext/census/census.proto')
-rw-r--r-- | src/core/ext/census/census.proto | 287 |
1 files changed, 287 insertions, 0 deletions
diff --git a/src/core/ext/census/census.proto b/src/core/ext/census/census.proto new file mode 100644 index 0000000000..6d95402b7b --- /dev/null +++ b/src/core/ext/census/census.proto @@ -0,0 +1,287 @@ +// Copyright 2016, Google Inc. +// All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +syntax = "proto3"; + +package google.census; + +import "google/protobuf/duration.proto"; +import "google/protobuf/timestamp.proto"; + +// All the census protos. +// +// Nomenclature note: capitalized names below (like Metric) are protos. +// +// Census lets you define a Metric - something which can be measured, like the +// latency of an RPC, the number of CPU cycles spent on an operation, or +// anything else you care to measure. You can record individual instances of +// measurements (a double value) for every metric of interest. These +// individual measurements are aggregated together into an Aggregation. There +// are two Aggregation types available: Distribution (describes the +// distribution of all measurements, possibly with a histogram) and +// IntervalStats (the count and mean of measurements across specified time +// periods). An Aggregation is described by an AggregationDescriptor. +// +// You can define how your stats are broken down by Tag values and which +// Aggregations to use through a View. The corresponding combination of +// Metric/View/Aggregation which is available to census clients is called a +// ViewAggregation. + +// Describes a metric +message Metric { + // name of metric, e.g. rpc_latency, cpu. + string name = 1; + + // More detailed description of the metric, used in documentation. + string description = 2; + + // Fundamental units of measurement supported by Census + // TODO(aveitch): expand this to include other S.I. units? + message BasicUnit { + enum Measure { + UNKNOWN = 0; + BITS = 1; + BYTES = 2; + SECS = 3; + CORES = 4; + MAX_UNITS = 5; + } + Measure type = 1; + } + + // MeasurementUnit lets you build compound units of the form + // 10^n * (A * B * ...) / (X * Y * ...), + // where the elements in the numerator and denominator are all BasicUnits. A + // MeasurementUnit must have at least one BasicUnit in its numerator. + // + // To specify multiplication in the numerator or denominator, simply specify + // multiple numerator or denominator fields. For example: + // + // - byte-seconds (i.e. bytes * seconds): + // numerator: BYTES + // numerator: SECS + // + // - events/sec^2 (i.e. rate of change of events/sec): + // numerator: COUNT + // denominator: SECS + // denominator: SECS + // + // To specify multiples (in power of 10) units, specify a non-zero prefix + // value, for example: + // + // - MB/s (i.e. megabytes / s): + // prefix: 6 + // numerator: BYTES + // denominator: SECS + // + // - nanoseconds + // prefix: -9 + // numerator: SECS + message MeasurementUnit { + int32 prefix = 1; + repeated BasicUnit numerator = 2; + repeated BasicUnit denominator = 3; + } + + // The units in which the Metric value is reported. + MeasurementUnit unit = 3; + + // Metrics will be assigned an ID when registered. Invalid if <= 0. + int32 id = 4; +} + +// An Aggregation summarizes a series of individual Metric measurements, an +// AggregationDescriptor describes an Aggregation +message AggregationDescriptor { + // At most one set of options. + oneof options { + // Defines the histogram bucket boundaries for Distributions + BucketBoundaries bucket_boundaries = 1; + // Defines the time windows to record for IntervalStats + IntervalBoundaries interval_boundaries = 2; + } + + // A Distribution may optionally contain a histogram of the values in the + // population. The bucket boundaries for that histogram is described by + // `bucket_boundaries`. + // + // Describes histogram bucket boundaries. Defines `size(bounds) + 1` (= N) + // buckets, with these boundaries for bucket index i: + // + // [-infinity, bounds[i]) for i == 0 + // [bounds[i-1], bounds[i]) for 0 < i < N-2 + // [bounds[i-1], +infinity) for i == N-1 + // + // i.e. an underflow bucket (number 0), zero or more finite buckets (1 + // through N - 2, and an overflow bucket (N - 1), with inclusive lower + // bounds and exclusive upper bounds. + // + // 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 BucketBoundaries { + // The values must be monotonically increasing. + repeated double bounds = 1; + } + + // For Interval stats, describe the size of each window. + message IntervalBoundaries { + // For each time window, specify a duration in seconds. + repeated double window_size = 1; + } +} + +// 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, as defined in +// Aggregation.bucket_options. +// +// 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. +// +// 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 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) + // + // If `count` is zero then this field must be zero. + double sum_of_squared_deviation = 3; + + // Describes a range of population values. + message Range { + // The minimum of the population values. + double min = 1; + // The maximum of the population values. + double max = 2; + } + + // The range of the population values. If `count` is zero, this field will not + // be defined. + Range range = 4; + + // A Distribution may optionally contain a histogram of the values in the + // population. The histogram is given in `bucket_count` as counts of values + // that fall into one of a sequence of non-overlapping buckets, as described + // by `AggregationDescriptor.options.bucket_boundaries`. + // The sum of the values in `bucket_counts` must equal the value in `count`. + // + // 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_count` must be no greater than N as defined in + // `bucket_boundaries`. + // + // Any suffix of trailing zero bucket_count fields may be omitted. + repeated int64 bucket_count = 5; +} + +// Record summary stats over various time windows. +message IntervalStats { + // Summary statistic over a single time window. + message Window { + // The window duration. + google.protobuf.Duration window_size = 1; + // The number of measurements in this window. + int64 count = 2; + // The arithmetic mean of all measurements in the window. + double mean = 3; + } + + // Full set of windows for this metric. + repeated Window window = 1; +} + +// A Tag: key-value pair +message Tag { + string key = 1; + string value = 2; +} + +// A View specifies an Aggregation and a set of tag keys. The Aggregation will +// be broken down by the unique set of matching tag values for each measurement. +message View { + // Name of view. + string name = 1; + + // More detailed description, for documentation purposes. + string description = 2; + + // ID of Metric to associate with this View. + int32 metric_id = 3; + + // Aggregation type to associate with this View. + AggregationDescriptor aggregation = 4; + + // Tag keys to match with a given Metric. If no keys are specified, then all + // stats for the Metric are recorded. Keys must be unique. + repeated string tag_key = 5; +} + +// An Aggregation summarizes a series of individual Metric measures. +message Aggregation { + // Name of this aggregation. + string name = 1; + + // More detailed description, for documentation purposes. + string description = 2; + + // The data for this Aggregation. + oneof data { + Distribution distribution = 3; + IntervalStats interval_stats = 4; + } + + // Tags associated with this Aggregation. + repeated Tag tag = 5; +} + +// A ViewAggregations represents all the Aggregations for a particular view. +message ViewAggregations { + // Aggregations - each will have a unique set of tag values for the tag_keys + // associated with the corresponding View. + repeated Aggregation aggregation = 1; + + // Start and end timestamps over which the value was accumulated. These + // values are not relevant/defined for IntervalStats aggregations, which are + // always accumulated over a fixed time period. + google.protobuf.Timestamp start = 2; + google.protobuf.Timestamp end = 3; +} |