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