|  | @@ -0,0 +1,318 @@
 | 
	
		
			
				|  |  | +// Copyright 2017, 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.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +//TODO(ericgribkoff) Depend on this directly from the instrumentation-proto
 | 
	
		
			
				|  |  | +//repository.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +syntax = "proto3";
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +package google.instrumentation;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +option java_package = "com.google.instrumentation.stats.proto";
 | 
	
		
			
				|  |  | +option java_outer_classname = "CensusProto";
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// All the census protos.
 | 
	
		
			
				|  |  | +//
 | 
	
		
			
				|  |  | +// Nomenclature notes:
 | 
	
		
			
				|  |  | +//   * Capitalized names below (like View) are protos.
 | 
	
		
			
				|  |  | +//   * Protos which describe types are named with a Descriptor suffix (e.g.
 | 
	
		
			
				|  |  | +//     MesurementDescriptor).
 | 
	
		
			
				|  |  | +//
 | 
	
		
			
				|  |  | +// Census lets you define the type and description of the data being measured
 | 
	
		
			
				|  |  | +// (e.g. the latency of an RPC or the number of CPU cycles spent on an
 | 
	
		
			
				|  |  | +// operation using MeasurementDescriptor. As individual measurements (a double
 | 
	
		
			
				|  |  | +// value) for are recorded, they 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 measurements (described by a MeasurementDescriptor)
 | 
	
		
			
				|  |  | +// are broken down by Tag values and which Aggregations to use through a
 | 
	
		
			
				|  |  | +// ViewDescriptor. The output (all measurements broken down by tag values into
 | 
	
		
			
				|  |  | +// specific Aggregations) is called a View.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// 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;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// MeasurementDescriptor describes a data point (measurement) type.
 | 
	
		
			
				|  |  | +message MeasurementDescriptor {
 | 
	
		
			
				|  |  | +  // A descriptive name, e.g. rpc_latency, cpu. Must be unique.
 | 
	
		
			
				|  |  | +  string name = 1;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // More detailed description of the resource, used in documentation.
 | 
	
		
			
				|  |  | +  string description = 2;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // Fundamental units of measurement supported by Census
 | 
	
		
			
				|  |  | +  // TODO(aveitch): expand this to include other S.I. units?
 | 
	
		
			
				|  |  | +  enum BasicUnit {
 | 
	
		
			
				|  |  | +    UNKNOWN = 0;    // Implementations should not use this
 | 
	
		
			
				|  |  | +    SCALAR = 1;     // Dimensionless
 | 
	
		
			
				|  |  | +    BITS = 2;       // A single bit
 | 
	
		
			
				|  |  | +    BYTES = 3;      // An 8-bit byte
 | 
	
		
			
				|  |  | +    SECONDS = 4;    // S.I. unit
 | 
	
		
			
				|  |  | +    CORES = 5;      // CPU core usage
 | 
	
		
			
				|  |  | +    MAX_UNITS = 6;  // Last defined value; implementations should only use
 | 
	
		
			
				|  |  | +                    // this for validation.
 | 
	
		
			
				|  |  | +  }
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // 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: SCALAR
 | 
	
		
			
				|  |  | +  //     denominator: SECS
 | 
	
		
			
				|  |  | +  //     denominator: SECS
 | 
	
		
			
				|  |  | +  //
 | 
	
		
			
				|  |  | +  // To specify multiples (in power of 10) of units, specify a non-zero
 | 
	
		
			
				|  |  | +  // 'power10' value, for example:
 | 
	
		
			
				|  |  | +  //
 | 
	
		
			
				|  |  | +  // - MB/s (i.e. megabytes / s):
 | 
	
		
			
				|  |  | +  //     power10: 6
 | 
	
		
			
				|  |  | +  //     numerator: BYTES
 | 
	
		
			
				|  |  | +  //     denominator: SECS
 | 
	
		
			
				|  |  | +  //
 | 
	
		
			
				|  |  | +  // - nanoseconds
 | 
	
		
			
				|  |  | +  //     power10: -9
 | 
	
		
			
				|  |  | +  //     numerator: SECS
 | 
	
		
			
				|  |  | +  message MeasurementUnit {
 | 
	
		
			
				|  |  | +    int32 power10 = 1;
 | 
	
		
			
				|  |  | +    repeated BasicUnit numerators = 2;
 | 
	
		
			
				|  |  | +    repeated BasicUnit denominators = 3;
 | 
	
		
			
				|  |  | +  }
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // The units used by this type of measurement.
 | 
	
		
			
				|  |  | +  MeasurementUnit unit = 3;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// An aggregation summarizes a series of individual measurements. There are
 | 
	
		
			
				|  |  | +// two types of aggregation (IntervalAggregation and DistributionAggregation),
 | 
	
		
			
				|  |  | +// unique types of each can be set using descriptors for each.
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// DistributionAggregation 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
 | 
	
		
			
				|  |  | +// DistributionAggregationDescriptor.bucket_bounds.
 | 
	
		
			
				|  |  | +//
 | 
	
		
			
				|  |  | +// The summary statistics are the count, mean, 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 DistributionAggregation {
 | 
	
		
			
				|  |  | +  // 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 the values in the population.  If `count` is zero then this
 | 
	
		
			
				|  |  | +  // field must be zero.
 | 
	
		
			
				|  |  | +  double sum = 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 `DistributionAggregationDescriptor.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_counts = 5;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // Tags associated with this DistributionAggregation. These will be filled
 | 
	
		
			
				|  |  | +  // in based on the View specification.
 | 
	
		
			
				|  |  | +  repeated Tag tags = 6;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +message DistributionAggregationDescriptor {
 | 
	
		
			
				|  |  | +  // A Distribution may optionally contain a histogram of the values in the
 | 
	
		
			
				|  |  | +  // population. The bucket boundaries for that histogram are described by
 | 
	
		
			
				|  |  | +  // `bucket_bounds`. This defines `size(bucket_bounds) + 1` (= N)
 | 
	
		
			
				|  |  | +  // buckets. The boundaries for bucket index i are:
 | 
	
		
			
				|  |  | +  //
 | 
	
		
			
				|  |  | +  // [-infinity, bucket_bounds[i]) for i == 0
 | 
	
		
			
				|  |  | +  // [bucket_bounds[i-1], bucket_bounds[i]) for 0 < i < N-2
 | 
	
		
			
				|  |  | +  // [bucket_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.
 | 
	
		
			
				|  |  | +  //
 | 
	
		
			
				|  |  | +  // If `bucket_bounds` has no elements (zero size), then there is no
 | 
	
		
			
				|  |  | +  // histogram associated with the Distribution. If `bucket_bounds` has only
 | 
	
		
			
				|  |  | +  // one element, there are no finite buckets, and that single element is the
 | 
	
		
			
				|  |  | +  // common boundary of the overflow and underflow buckets. The values must
 | 
	
		
			
				|  |  | +  // be monotonically increasing.
 | 
	
		
			
				|  |  | +  repeated double bucket_bounds = 1;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// An IntervalAggreation records summary stats over various time
 | 
	
		
			
				|  |  | +// windows. These stats are approximate, with the degree of accuracy
 | 
	
		
			
				|  |  | +// controlled by setting the n_sub_intervals parameter in the
 | 
	
		
			
				|  |  | +// IntervalAggregationDescriptor.
 | 
	
		
			
				|  |  | +message IntervalAggregation {
 | 
	
		
			
				|  |  | +  // Summary statistic over a single time interval.
 | 
	
		
			
				|  |  | +  message Interval {
 | 
	
		
			
				|  |  | +    // The interval duration. Must be positive.
 | 
	
		
			
				|  |  | +    Duration interval_size = 1;
 | 
	
		
			
				|  |  | +    // Approximate number of measurements recorded in this interval.
 | 
	
		
			
				|  |  | +    double count = 2;
 | 
	
		
			
				|  |  | +    // The cumulative sum of measurements in this interval.
 | 
	
		
			
				|  |  | +    double sum = 3;
 | 
	
		
			
				|  |  | +  }
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // Full set of intervals for this aggregation.
 | 
	
		
			
				|  |  | +  repeated Interval intervals = 1;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // Tags associated with this IntervalAggregation. These will be filled in
 | 
	
		
			
				|  |  | +  // based on the View specification.
 | 
	
		
			
				|  |  | +  repeated Tag tags = 2;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// An IntervalAggreationDescriptor specifies time intervals for an
 | 
	
		
			
				|  |  | +// IntervalAggregation.
 | 
	
		
			
				|  |  | +message IntervalAggregationDescriptor {
 | 
	
		
			
				|  |  | +  // Number of internal sub-intervals to use when collecting stats for each
 | 
	
		
			
				|  |  | +  // interval. The max error in interval measurements will be approximately
 | 
	
		
			
				|  |  | +  // 1/n_sub_intervals (although in practice, this will only be approached in
 | 
	
		
			
				|  |  | +  // the presence of very large and bursty workload changes), and underlying
 | 
	
		
			
				|  |  | +  // memory usage will be roughly proportional to the value of this
 | 
	
		
			
				|  |  | +  // field. Must be in the range [2, 20]. A value of 5 will be used if this is
 | 
	
		
			
				|  |  | +  // unspecified.
 | 
	
		
			
				|  |  | +  int32 n_sub_intervals = 1;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // The size of each interval, as a time duration. Must have at least one
 | 
	
		
			
				|  |  | +  // element.
 | 
	
		
			
				|  |  | +  repeated Duration interval_sizes = 2;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// A Tag: key-value pair.
 | 
	
		
			
				|  |  | +message Tag {
 | 
	
		
			
				|  |  | +  string key = 1;
 | 
	
		
			
				|  |  | +  string value = 2;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// A ViewDescriptor specifies an AggregationDescriptor and a set of tag
 | 
	
		
			
				|  |  | +// keys. Views instantiated from this descriptor will contain Aggregations
 | 
	
		
			
				|  |  | +// broken down by the unique set of matching tag values for each measurement.
 | 
	
		
			
				|  |  | +message ViewDescriptor {
 | 
	
		
			
				|  |  | +  // Name of view. Must be unique.
 | 
	
		
			
				|  |  | +  string name = 1;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // More detailed description, for documentation purposes.
 | 
	
		
			
				|  |  | +  string description = 2;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // Name of a MeasurementDescriptor to be used for this view.
 | 
	
		
			
				|  |  | +  string measurement_descriptor_name = 3;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // Aggregation type to associate with View.
 | 
	
		
			
				|  |  | +  oneof aggregation {
 | 
	
		
			
				|  |  | +    IntervalAggregationDescriptor interval_aggregation = 4;
 | 
	
		
			
				|  |  | +    DistributionAggregationDescriptor distribution_aggregation = 5;
 | 
	
		
			
				|  |  | +  }
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // Tag keys to match with a given measurement. If no keys are specified,
 | 
	
		
			
				|  |  | +  // then all stats are recorded. Keys must be unique.
 | 
	
		
			
				|  |  | +  repeated string tag_keys = 6;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// DistributionView contains all aggregations for a view specified using a
 | 
	
		
			
				|  |  | +// DistributionAggregationDescriptor.
 | 
	
		
			
				|  |  | +message DistributionView {
 | 
	
		
			
				|  |  | +  // Aggregations - each will have a unique set of tag values for the tag_keys
 | 
	
		
			
				|  |  | +  // associated with the corresponding View.
 | 
	
		
			
				|  |  | +  repeated DistributionAggregation aggregations = 1;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  // Start and end timestamps over which aggregations was accumulated.
 | 
	
		
			
				|  |  | +  Timestamp start = 2;
 | 
	
		
			
				|  |  | +  Timestamp end = 3;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// IntervalView contains all aggregations for a view specified using a
 | 
	
		
			
				|  |  | +// IntervalAggregationDescriptor.
 | 
	
		
			
				|  |  | +message IntervalView {
 | 
	
		
			
				|  |  | +  // Aggregations - each will have a unique set of tag values for the tag_keys
 | 
	
		
			
				|  |  | +  // associated with the corresponding View.
 | 
	
		
			
				|  |  | +  repeated IntervalAggregation aggregations = 1;
 | 
	
		
			
				|  |  | +}
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +// A View contains the aggregations based on a ViewDescriptor.
 | 
	
		
			
				|  |  | +message View {
 | 
	
		
			
				|  |  | +  // ViewDescriptor name associated with this set of View.
 | 
	
		
			
				|  |  | +  string view_name = 1;
 | 
	
		
			
				|  |  | +
 | 
	
		
			
				|  |  | +  oneof view {
 | 
	
		
			
				|  |  | +    DistributionView distribution_view = 2;
 | 
	
		
			
				|  |  | +    IntervalView interval_view = 3;
 | 
	
		
			
				|  |  | +  }
 | 
	
		
			
				|  |  | +}
 |