tools/grpcz/census.proto

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