config/metrics.proto - cobalt - Git at Google

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

   // ID of the defult encoding scheme to use to encode this MetricPart if no
   // other encoding ID is given.
   uint32 default_encoding_id = 4;
 }

 // 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: 11

   // 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 ShufflerBackend specifies which backend an observation should be sent to.
   enum ShufflerBackend {
     // The legacy GRPC GKE backend
     LEGACY_BACKEND = 0;
     // The first version of the clearcut backend.
     V1_BACKEND = 1;
   }
   // Specifies a destination where observations should be sent.
   ShufflerBackend backend = 9;

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

   message Metadata {
     // The time after which this metric is no longer valid. If this field is not
     // supplied, the metric is considered currently expired, and is not
     // guaranteed to be reported by cobalt.
     //
     // Note: This should be a date encoded as yyyy/mm/dd and should not be
     // further than 1 year in the future.
     string expires_after = 1;

     // Primary contact for questions/bugs regarding this metric (may be a
     // group). This should be a fully qualified email address (e.g.
     // my-group@test.com)
     string owner = 2;

     // This represents the highest stage of build for which a metric will be
     // reported. A DEBUG metric will not be reported in FISHFOOD or above, etc.
     // A metric that should always be reported should have a value of PROD.
     // The list of metrics with this value should be kept as small as feasible.
     enum BuildLevel {
       NEVER_REPORT = 0;

       // These should all be the same as BuildLevel in observation.proto.
       DEBUG = 10;
       FISHFOOD = 20;
       DOGFOOD = 40;
       PROD = 99;
     }
     BuildLevel max_build_level = 4;
   }
   Metadata meta_data = 10;
 }

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

	// ID of the defult encoding scheme to use to encode this MetricPart if no
	// other encoding ID is given.
	uint32 default_encoding_id = 4;
	}

	// 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: 11

	// 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 ShufflerBackend specifies which backend an observation should be sent to.
	enum ShufflerBackend {
	// The legacy GRPC GKE backend
	LEGACY_BACKEND = 0;
	// The first version of the clearcut backend.
	V1_BACKEND = 1;
	}
	// Specifies a destination where observations should be sent.
	ShufflerBackend backend = 9;

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

	message Metadata {
	// The time after which this metric is no longer valid. If this field is not
	// supplied, the metric is considered currently expired, and is not
	// guaranteed to be reported by cobalt.
	//
	// Note: This should be a date encoded as yyyy/mm/dd and should not be
	// further than 1 year in the future.
	string expires_after = 1;

	// Primary contact for questions/bugs regarding this metric (may be a
	// group). This should be a fully qualified email address (e.g.
	// my-group@test.com)
	string owner = 2;

	// This represents the highest stage of build for which a metric will be
	// reported. A DEBUG metric will not be reported in FISHFOOD or above, etc.
	// A metric that should always be reported should have a value of PROD.
	// The list of metrics with this value should be kept as small as feasible.
	enum BuildLevel {
	NEVER_REPORT = 0;

	// These should all be the same as BuildLevel in observation.proto.
	DEBUG = 10;
	FISHFOOD = 20;
	DOGFOOD = 40;
	PROD = 99;
	}
	BuildLevel max_build_level = 4;
	}
	Metadata meta_data = 10;
	}

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