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