diff options
Diffstat (limited to 'tools/grpcz/census.proto')
| -rw-r--r-- | tools/grpcz/census.proto | 318 |
1 files changed, 318 insertions, 0 deletions
diff --git a/tools/grpcz/census.proto b/tools/grpcz/census.proto new file mode 100644 index 0000000000..d1ff69400b --- /dev/null +++ b/tools/grpcz/census.proto @@ -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; + } +} |