aboutsummaryrefslogtreecommitdiffhomepage
path: root/src/proto
diff options
context:
space:
mode:
authorGravatar Alistair Veitch <aveitch@google.com>2016-05-24 10:08:07 -0700
committerGravatar Alistair Veitch <aveitch@google.com>2016-05-24 10:08:07 -0700
commitfb461babb509fc9e3a604341d70ee66a47e0df11 (patch)
tree0014eaf62a9e1970df3b8ed166184d4c22ac81d5 /src/proto
parent8fc19a1fa556527a5a0264ae7ccd358f87ae81bc (diff)
really commit
Diffstat (limited to 'src/proto')
-rw-r--r--src/proto/census/census.options3
-rw-r--r--src/proto/census/census.proto313
2 files changed, 316 insertions, 0 deletions
diff --git a/src/proto/census/census.options b/src/proto/census/census.options
new file mode 100644
index 0000000000..747740cc3e
--- /dev/null
+++ b/src/proto/census/census.options
@@ -0,0 +1,3 @@
+google.census.Tag.key max_size:255
+google.census.Tag.value max_size:255
+google.census.View.tag_keys max_count 15 \ No newline at end of file
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;
+}