diff options
Diffstat (limited to 'src/proto/census/census.proto')
| -rw-r--r-- | src/proto/census/census.proto | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/src/proto/census/census.proto b/src/proto/census/census.proto new file mode 100644 index 0000000000..c869d851ff --- /dev/null +++ b/src/proto/census/census.proto @@ -0,0 +1,313 @@ +// 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; + +// 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. + + +// The following two types are copied from +// google/protobuf/{duration,timestamp}.proto. Ideally, we would be able to +// import them, but this causes compilation issues on C-based systems +// (e.g. https://koti.kapsi.fi/jpa/nanopb/), which cannot process the C++ +// headers generated from the standard protobuf distribution. See the relevant +// proto files for full documentation of these types. + +message Duration { + // Signed seconds of the span of time. Must be from -315,576,000,000 + // to +315,576,000,000 inclusive. + int64 seconds = 1; + + // Signed fractions of a second at nanosecond resolution of the span + // of time. Durations less than one second are represented with a 0 + // `seconds` field and a positive or negative `nanos` field. For durations + // of one second or more, a non-zero value for the `nanos` field must be + // of the same sign as the `seconds` field. Must be from -999,999,999 + // to +999,999,999 inclusive. + int32 nanos = 2; +} + +message Timestamp { + // Represents seconds of UTC time since Unix epoch + // 1970-01-01T00:00:00Z. Must be from from 0001-01-01T00:00:00Z to + // 9999-12-31T23:59:59Z inclusive. + int64 seconds = 1; + + // Non-negative fractions of a second at nanosecond resolution. Negative + // second values with fractions must still have non-negative nanos values + // that count forward in time. Must be from 0 to 999,999,999 + // inclusive. + int32 nanos = 2; +} + +// 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. If neither option is set, a default type + // of Distribution (without a histogram component) will be used. + 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 (for size(bounds) >= 1; if size(bounds) == 0, then no histogram + // will be defined. The boundaries for bucket index i are: + // + // [-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` field 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; + + // 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 = 3; + + // 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 = 4; +} + +// Record summary stats over various time windows. +message IntervalStats { + // Summary statistic over a single time window. + message Window { + // The window duration. + 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. + Timestamp start = 2; + Timestamp end = 3; +} |