| // Copyright 2016 The Fuchsia 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 cobalt; |
| |
| option go_package = "config"; |
| |
| // A specification of a field from SystemProfile. These are used in a Metric to |
| // specify which fields should be included in collected Observations and they |
| // are used in a ReportConfig to specify which fields should be included in each |
| // row of a generated report. |
| enum SystemProfileField { |
| OS = 0; |
| ARCH = 1; |
| BOARD_NAME = 2; |
| PRODUCT_NAME = 3; |
| } |
| |
| // ExponentialIntegerBuckets is used to define a partition of the integers into |
| // a finite number of buckets of exponentially-increasing size. |
| // |
| // Let n = num_buckets. Then there are n+2 buckets indexed 0,...,n+1. |
| // Bucket 0 is the underflow bucket: (-infinity, floor) |
| // Bucket n+1 is the overflow bucket: |
| // [lower + initial_step * step_multiplier ^ n, +infinity) |
| // |
| // For i = 1 to n, the bucket i is defined as |
| // [floor + initial_step * step_multiplier ^ (i-1), floor + initial_step * |
| // step_multiplier ^ i) |
| // |
| // Example: floor = 0, num_buckets = 3, initial_step = 10, step_multiplier = 10. |
| // (-infinity, 0), [0, 10), [10, 100), [100, 1000), [1000, +inifinity) |
| message ExponentialIntegerBuckets { |
| int64 floor = 1; |
| |
| // num_buckets must be at least 1. |
| uint32 num_buckets = 2; |
| |
| // Must be at least one. |
| uint32 initial_step = 3; |
| |
| // Must be at least one. |
| uint32 step_multiplier = 4; |
| }; |
| |
| // LinearIntegerBuckets is used to define a partition of the integers into a |
| // finite number of buckets of equal size. |
| // |
| // Let n = num_buckets. Then there are n+2 buckets indexed 0,...,n+1. |
| // Bucket 0 is the underflow bucket: (-infinity, floor) |
| // Bucket n+1 is the overflow bucket: [lower + step_size * n, +infinity) |
| // |
| // For i = 1 to n, the bucket i is defined as |
| // [floor + step_size * (i-1), floor + step_size * i) |
| // |
| // Example: floor = 0, num_buckets = 3, step_size = 10. |
| // (-infinity, 0), [0, 10), [10, 20), [20, 30), [30, +inifinity) |
| message LinearIntegerBuckets { |
| int64 floor = 1; |
| |
| // Must be at least one. |
| uint32 num_buckets = 2; |
| |
| // Must be at least one. |
| uint32 step_size = 3; |
| } |
| |
| message IntegerBuckets { |
| oneof buckets { |
| ExponentialIntegerBuckets exponential = 1; |
| LinearIntegerBuckets linear = 2; |
| } |
| }; |
| |
| // A |Metric| is composed of one or more |MetricParts|. A |MetricPart| has a |
| // name which is specified as the key in the |parts| field of |Metric|, a |
| // description and a data type which specifies the type of a |ValuePart| that |
| // should be encoded for this MetricPart. |
| message MetricPart { |
| enum DataType { |
| // Values for this MetricPart are human-readable strings. Cobalt may |
| // display the strings in generated reports. A |ValuePart| for this |
| // MetricPart must have its |string_value| set. |
| STRING = 0; |
| |
| // Values for this MetricPart are integers. A |ValuePart| encoded for this |
| // MetricPart must have its |int_value| set. |
| INT = 1; |
| |
| // Values for this MetricPart are uninterpreted sequences of bytes. Cobalt |
| // will not try to interpret or display these values. A |ValuePart| encoded |
| // for this MetricPart must have its |blob_value| set. |
| BLOB = 2; |
| |
| // Values for this MetricPart are non-negative integers that are |
| // interpreted as zero-based indices into some enumerated set that is |
| // specified outside of Cobalt's configuration. Human-readable labels may |
| // be associated with the indices in a Cobalt ReportConfig for the purpose |
| // of generating reports about this metric. During report generation, in |
| // case the ReportConfig does not specify a label for an index that occurs |
| // in the data, no error will occur but rather a temporary place-holder |
| // label such as "<index 42 (undefined)>" will be generated. |
| // |
| // Additionally, a maximum value for the indices may be specified by an |
| // EncodingConfig if the associated encoding mechanism requires it. |
| // |
| // A |ValuePart| for this MetricPart must have its |index_value| set. |
| INDEX = 3; |
| |
| // Values for this MetricPart are double-precision floating point numbers. |
| // A |ValuePart| encoded for this MetricPart must have its |double_value| |
| // set. |
| DOUBLE = 4; |
| } |
| |
| // A human-readable description of this MetricPart. This should include |
| // a specification of the "semantic type" of this part. For example the |
| // description might include the phrase "This is an eTLD+1." |
| string description = 1; |
| |
| // The data-type for this MetricPart. |
| DataType data_type = 2; |
| |
| // This may only be set if |data_type| is |INT|. If this is set, a ValuePart |
| // for this MetricPart may contain a BucketDistribution instead of an int. In |
| // that case the ValuePart represents many integer observations rather than a |
| // single integer observation. |
| // |
| // Only one MetricPart per Metric may have this field set. |
| IntegerBuckets int_buckets = 3; |
| } |
| |
| // A Metric represents a real-world value to be observed and reported by Cobalt. |
| // For example "Fuchsia Usage Hour-of-the-day" might be a metric that measures |
| // Fuchsia system usage as a function of the hour of the day. |
| // Each Observation from the Encoder is for a particular metric. |
| // Each Observation for the metric "Fuchsia Usage Hour-of-the-day" would |
| // report the hour of the day for a particular usage of Fuchsia. |
| // A Metric has one or more named parts and each Observation sent by the Encoder |
| // must contain ObservationParts corresponding to these Metric parts. |
| // For example the Metric described above might have only one part named |
| // "hour" and so each Observation for this metric should have a single |
| // ObservationPart named "hour". On the other hand the Metric "Fuchsia Usage |
| // City-and-Rating" might have two parts called "City" and "Rating". |
| message Metric { |
| // Next ID: 9 |
| |
| // These three numbers form this Metric's unique ID in the Cobalt Config |
| // DB. |
| uint32 customer_id = 1; |
| uint32 project_id = 2; |
| uint32 id = 3; |
| |
| string name = 4; |
| string description = 5; |
| |
| // The keys are the names of the part. |
| map<string, MetricPart> parts = 6; |
| |
| // The list of SystemProfileFields to include in the metadata for each |
| // observation. When sent to the Shuffler this will be sent only once per |
| // ObservationBatch. |
| repeated SystemProfileField system_profile_field = 8; |
| |
| // A TimeZonePolicy specifies how the day_index of an Observation should |
| // be computed based on the actual time of encoding. |
| enum TimeZonePolicy { |
| // There is no default. Either LOCAL or UTC must be specified. |
| UNSET = 0; |
| |
| // Use the local date at encoding time to compute the day_index. |
| LOCAL = 1; |
| |
| // Use the date in UTC at encoding time to compute the day_index. |
| UTC = 2; |
| } |
| |
| // Which TimeZonePolicy should Encoders use when encoding Observations for |
| // this metric? |
| TimeZonePolicy time_zone_policy = 7; |
| } |
| |
| // Constains the list of all Metrics that are registered in the |
| // Cobalt system. An instance of RegisteredMetrics is deserialized |
| // from a text file. |
| message RegisteredMetrics { |
| repeated Metric element = 1; |
| } |