From c5d48acbb2cb32687ca09177a313f5fcd47103fe Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Mon, 30 Apr 2018 13:00:05 +0300 Subject: [PATCH] Initial draft for a metrics, an API for exporters. (#53) * Initial draft for a metrics API that can be used by the stats API as well as other metric systems. * Fix comments, move metrics under stats/metrics * Fix more comments. Rename MetricPoint to Metric. --- build.gradle | 1 + opencensus/proto/stats/metrics/BUILD.bazel | 33 ++++ opencensus/proto/stats/metrics/metrics.proto | 197 +++++++++++++++++++ pom.xml | 1 + 4 files changed, 232 insertions(+) create mode 100644 opencensus/proto/stats/metrics/BUILD.bazel create mode 100644 opencensus/proto/stats/metrics/metrics.proto diff --git a/build.gradle b/build.gradle index e1b1239..d05ba48 100644 --- a/build.gradle +++ b/build.gradle @@ -25,6 +25,7 @@ sourceSets { proto { // In addition to the default 'src/main/proto' srcDir 'opencensus/proto/stats' + srcDir 'opencensus/proto/stats/metrics' srcDir 'opencensus/proto/trace' } } diff --git a/opencensus/proto/stats/metrics/BUILD.bazel b/opencensus/proto/stats/metrics/BUILD.bazel new file mode 100644 index 0000000..c31deab --- /dev/null +++ b/opencensus/proto/stats/metrics/BUILD.bazel @@ -0,0 +1,33 @@ +# Copyright 2018, OpenCensus Authors +# +# 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. + +package(default_visibility = ["//visibility:public"]) + +proto_library( + name = "metrics_proto", + srcs = ["metrics.proto"], + deps = [ + "@com_google_protobuf//:timestamp_proto", + ], +) + +cc_proto_library( + name = "metrics_proto_cc", + deps = [":metrics_proto"], +) + +java_proto_library( + name = "metrics_proto_java", + deps = [":metrics_proto"], +) diff --git a/opencensus/proto/stats/metrics/metrics.proto b/opencensus/proto/stats/metrics/metrics.proto new file mode 100644 index 0000000..5e0c18b --- /dev/null +++ b/opencensus/proto/stats/metrics/metrics.proto @@ -0,0 +1,197 @@ +// Copyright 2018, OpenCensus Authors +// +// 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. + +syntax = "proto3"; + +package opencensus.proto.stats.metrics; + +import "google/protobuf/timestamp.proto"; + +option go_package = "metricsproto"; +option java_multiple_files = true; +option java_package = "io.opencensus.proto.metrics"; +option java_outer_classname = "MetricsProto"; + +// A collection of Metrics. +message MetricSet { + // Each Metric has one or more timeseries. + repeated Metric metrics = 1; +} + +// Defines a Metric which has one or more timeseries. +message Metric { + // The description of the metric. + MetricDescriptor metric_descriptor = 1; + + // One or more timeseries for a single metric, where each timeseries has + // one or more points. + repeated TimeSeries timeseries = 2; +} + +// Defines a metric type and its schema. +message MetricDescriptor { + // TODO: Add restrictions for characters that can be used. + // The metric type, including its DNS name prefix. It must be unique. + string name = 1; + + // A detailed description of the metric, which can be used in documentation. + string description = 2; + + // The unit in which the metric value is reported. Follows the format + // described by http://unitsofmeasure.org/ucum.html. + string unit = 3; + + // The kind of metric. It describes how the data is reported. + enum Type { + // Do not use this default value. + UNSPECIFIED = 0; + + // An instantaneous measurement of a value. + GAUGE = 1; + + // A value accumulated over a time interval. Cumulative measurements in a + // time series should have the same start time and increasing end times, + // until an event resets the cumulative value to zero and sets a new + // start time for the following points. + CUMULATIVE = 2; + } + Type type = 4; + + // TODO: Consider to add LabelInfo{key, description} if needed. +} + +// A collection of data points that describes the time-varying values +// of a metric. +message TimeSeries { + // TODO: Add restrictions for characters that can be used for keys and values. + // The set of label values that uniquely identify this timeseries. Apply to all + // points. + map label = 1; + + // The data points of this timeseries. Point type MUST match the MetricDescriptor.type, so for + // a CUMULATIVE type only cumulative_points are present and for a GAUGE type only gauge_points + // are present. + repeated GaugePoint gauge_points = 2; + repeated CumulativePoint cumulative_points = 3; +} + +// An instantaneous measurement of a value. +message GaugePoint { + // The moment when this gauge point was recorded. + google.protobuf.Timestamp timestamp = 1; // required + + // The actual point value. + oneof value { + // A 64-bit integer. + int64 int64_value = 2; + + // A 64-bit double-precision floating-point number. + double double_value = 3; + + // TODO: Add support for Summary type. + } +} + +// Measurements accumulated over a time interval. +message CumulativePoint { + // This must be the same until an event resets the cumulative value to zero + // and sets a new start for the following points. + google.protobuf.Timestamp start_time = 1; // required + + // The end timestamp of the accumulated measurement. + google.protobuf.Timestamp end_time = 2; // required + + // The actual point value. + oneof value { + // A 64-bit integer. + int64 int64_value = 3; + + // A 64-bit double-precision floating-point number. + double double_value = 4; + + // A distribution value. + DistributionValue distribution_value = 5; + } +} + +// Distribution contains summary statistics for a population of values. It +// optionally contains a histogram representing the distribution of those +// values across a set of buckets. +message DistributionValue { + // The number of values in the population. Must be non-negative. This value + // must equal the sum of the values in bucket_counts if a histogram is + // provided. + 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 squared deviations from the mean of the values in the + // population. For values x_i this is: + // + // Sum[i=1..n]((x_i - mean)^2) + // + // Knuth, "The Art of Computer Programming", Vol. 2, page 323, 3rd edition + // describes Welford's method for accumulating this sum in one pass. + // + // If count is zero then this field must be zero. + double sum_of_squared_deviation = 3; + + // The range of the population values. + message Range { + // The minimum of the population values. + double min = 1; + + // The maximum of the population values. + double max = 2; + } + + // If specified, contains the range of the population values. The field + // must not be present if the count is zero. + Range range = 4; + + // 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 = 5; + + message Bucket { + // The number of values in each bucket of the histogram, as described in + // bucket_bounds. + int64 count = 1; + + // TODO: Add support for exemplars. + } + + // If the distribution does not have a histogram, then omit this field. + // If there is a histogram, then the sum of the values in the Bucket counts + // must equal the value in the count field of the distribution. + repeated Bucket buckets = 6; +} diff --git a/pom.xml b/pom.xml index 2a33896..c4c2185 100644 --- a/pom.xml +++ b/pom.xml @@ -53,6 +53,7 @@ . opencensus/proto/stats/*.proto + opencensus/proto/stats/metrics/*.proto opencensus/proto/trace/*.proto