src/registry/metric_definition.proto - cobalt - Git at Google

 // Copyright 2018 The Fuchsia Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 syntax = "proto3";

 package cobalt;

 import "src/registry/annotations.proto";
 import "src/registry/report_definition.proto";

 option go_package = "src/registry;config";

 // A Metric is a category of Events that a user logs to Cobalt.
 //
 // A Metric belongs to a Project and has a name and a type.
 //
 // When an Event is logged in Cobalt's Logger interface, a Metric is
 // specified and the Event then belongs to that Metric.
 //
 // A MetricDefinition includes a list of ReportDefinitions. These are the
 // definitions of the Reports that should be run for that Metric. Generating a
 // Report involves the Cobalt client sending Observations to the server based
 // on the Events belonging to the Metric, and the server performing an analysis
 // of those Observations in order to generate the Report output.
 //
 // When an Observation is sent from a Cobalt client to the server, it contains
 // a Metric id and a Report id. This indicates that the
 // Observation is derived from the Events belonging to the Metric for the
 // purpose of generating the Report.
 //
 // A MetricDefinition is used to define a Metric.
 //
 // Next ID: 26
 message MetricDefinition {
   reserved 6, 7, 9, 17;
   reserved "event_codes", "max_event_code", "parts", "event_code_buffer_max";

   // Unique name for this Metric within its owning project.
   // The name must obey the syntax of a C variable name and must have length
   // at most 64.
   string metric_name = 1;

   // The Cobalt registry YAML parser will automatically set the values of
   // customer_name and project_name based on the context of the YAML file.
   string customer_name = 14 [(cobalt_options).hide_on_client = true];
   string project_name = 15 [(cobalt_options).hide_on_client = true];

   // These three numbers form this Metric's unique numerical ID in Cobalt. The
   // Cobalt registry YAML parser will automatically set the value of
   // customer_id and project_id based on the context of the YAML file.
   // The user must manually set the |id| field to a number uniquely identifying
   // this Metric within its project.
   uint32 customer_id = 2;
   uint32 project_id = 3;
   uint32 id = 4;

   // This field should only be used for migrating a Cobalt 1.0 metric to a Cobalt 1.1 metric. Any
   // events that are logged to this metric will be mirrored to replacement_metric. This field should
   // be set only on 1.0 metrics, and include the metric_id of the replacement 1.1 metric.
   uint32 replacement_metric_id = 23;
   // This field should be used to document why a metric is not being migrated to Cobalt 1.1.
   string no_replacement_metric = 24 [(cobalt_options).hide_on_client = true];

   // A Metric has one of the following types.
   // Next ID: 12
   enum MetricType {
     reserved 7;
     reserved "STRING_USED";

     UNSET = 0;

     // Records that an event has occurred.
     //
     // Event fields:
     // - uint32 event_code # The event_code for the event that occurred.
     //
     // MetricDefinition fields:
     // - event_codes # Enumerated list of all possible event types
     // - metric_dimensions # Extra user-defined dimensions for this metric. Each
     //                       dimension consists of an enumerated set of event
     //                       codes. (For metrics of type EVENT_OCCURRED there
     //                       must be exactly one).
     // - max_num_event_codes # Upper bound on future growth of event_codes
     //
     // Compatible report types:
     // - SIMPLE_OCCURRENCE_COUNT
     // - UNIQUE_N_DAY_ACTIVES
     //
     // TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
     EVENT_OCCURRED = 1;

     // Records that an event occurred a number of times.
     //
     // Event fields:
     // - repeated uint32 event_code # The event codes for the event that
     //                                occurred. There must be one event code
     //                                given for each dimension specified in the
     //                                metric definition.
     // - string component # The associated system component
     // - int64 period_duration_micros # Time over which the count was taken
     // - uint32 count # The number of times the event occurred.
     //
     // MetricDefinition fields:
     // - event_codes  # Enumerated list of all possible event types
     // - metric_dimensions # Extra user-defined dimensions for this metric. Each
     //                       dimension consists of an enumerated set of event
     //                       codes.
     //
     // Compatible report types:
     // - EVENT_COMPONENT_OCCURRENCE_COUNT
     // - INT_RANGE_HISTOGRAM
     // - NUMERIC_AGGREGATION
     // - PER_DEVICE_NUMERIC_STATS
     // - PER_DEVICE_HISTOGRAM
     //
     // TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
     EVENT_COUNT = 2;

     // Records an elapsed time.
     //
     // Event fields:
     // - repeated uint32 event_code # The event codes for the event that
     //                                occurred. There must be one event code
     //                                given for each dimension specified in the
     //                                metric definition.
     // - string component # The associated system component
     // - int64 elapsed_micros # The elapsed time in microseconds.
     //
     // MetricDefinition fields:
     // - event_codes # Enumerated list of all possible event types
     // - metric_dimensions # Extra user-defined dimensions for this metric. Each
     //                       dimension consists of an enumerated set of event
     //                       codes.
     //
     // Compatible report types:
     // - NUMERIC_AGGREGATION
     // - INT_RANGE_HISTOGRAM
     // - PER_DEVICE_NUMERIC_STATS
     // - PER_DEVICE_HISTOGRAM
     //
     // TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
     ELAPSED_TIME = 3;

     // Records a frame-rate.
     //
     // Event fields:
     // - repeated uint32 event_code # The event codes for the event that
     //                                occurred. There must be one event code
     //                                given for each dimension specified in the
     //                                metric definition.
     // - string component # The associated system component
     // - int32 frame_rate # round(frames-per-second * 1000)
     //
     // MetricDefinition fields:
     // - event_codes  # Enumerated list of all possible event types
     // - metric_dimensions # Extra user-defined dimensions for this metric. Each
     //                       dimension consists of an enumerated set of event
     //                       codes.
     //
     // Compatible report types:
     // - NUMERIC_AGGREGATION
     // - INT_RANGE_HISTOGRAM
     // - PER_DEVICE_NUMERIC_STATS
     // - PER_DEVICE_HISTOGRAM
     //
     // TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
     FRAME_RATE = 4;

     // Records a memory-usage.
     //
     // Event fields:
     // - repeated uint32 event_code # The event codes for the event that
     //                                occurred. There must be one event code
     //                                given for each dimension specified in the
     //                                metric definition.
     // - string component # The associated system component
     // - int64 bytes # Memory usage in bytes.
     //
     // MetricDefinition fields:
     // - event_codes  # Enumerated list of all possible event types
     // - metric_dimensions # Extra user-defined dimensions for this metric. Each
     //                       dimension consists of an enumerated set of event
     //                       codes.
     //
     // Compatible report types:
     // - NUMERIC_AGGREGATION
     // - INT_RANGE_HISTOGRAM
     // - PER_DEVICE_NUMERIC_STATS
     // - PER_DEVICE_HISTOGRAM
     //
     // TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
     MEMORY_USAGE = 5;

     // Records a histogram over a set of integer buckets. The semantics of the
     // Metric must be specified in comments near the Metric definition. The
     // numerical values of the buckets is specified below in the |int_buckets|
     // field.
     //
     // This Metric type is intended to be used in situations where the client
     // wishes to aggregate a large number of integer-valued measurements
     // *in-process*, prior to submitting the data to Cobalt.
     //
     // Event fields:
     // - repeated uint32 event_code # The event codes for the event that
     //                                occurred. There must be one event code
     //                                given for each dimension specified in the
     //                                metric definition.
     // - string component # The associated system component
     // - vector<HistogramBucket> histogram # The histogram being logged.
     //
     // MetricDefinition fields:
     // - int_buckets # The definition of the buckets
     // - event_codes  # Enumerated list of all possible event types
     // - metric_dimensions # Extra user-defined dimensions for this metric. Each
     //                       dimension consists of an enumerated set of event
     //                       codes.
     //
     // Compatible report types:
     // - INT_RANGE_HISTOGRAM
     //
     // TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
     INT_HISTOGRAM = 6;

     // Records that an event has occurred one or many times.
     //
     // MetricDefinition fields:
     // - metric_dimensions (0 or more)
     // - metric_semantics (required)
     OCCURRENCE = 8;

     // Records an integer measurement.
     //
     // MetricDefinition fields:
     // - metric_dimensions (0 or more)
     // - metric_units (Either this field or metric_units_other is required.)
     // - metric_units_other (Either metric_units or this field is required.)
     // - metric_semantics (required)
     INTEGER = 9;

     // Records many approximate integer measurements.
     //
     // MetricDefinition fields:
     // - metric_dimensions (0 or more)
     // - int_buckets
     // - metric_units (Either this field or metric_units other is required.)
     // - metric_units_other (Either metric_units or this field is required.)
     // - metric_semantics (required)
     INTEGER_HISTOGRAM = 10;

     // Records the fact that a string was observed.
     //
     // MetricDefinition fields:
     // - metric_dimensions (0 or more)
     // - metric_semantics (required)
     // - string_candidate_file. (required)
     // - string_buffer_max (required)
     STRING = 11;

     // Allows users of Cobalt to define custom Metrics with custom semantics and
     // their own data type. A metric of this type is associated with a protocol
     // buffer definition and proto messages of that type will be populated with
     // the data logged for this metric. The semantics of the Metric should be
     // specified in the .proto file. Each event logged for this Metric must have
     // dimensions with names and types that correspond to the fields of the
     // associated proto or the serialized proto itself.
     //
     // Event fields:
     //   vector<CustomEventValue> event_values # Named, typed values
     //
     // MetricDefinition fields:
     // - proto_name # The fully qualified name of the protobuf associated with
     //                this Metric.
     //
     // Compatible report types:
     // - CUSTOM_RAW_DUMP
     CUSTOM = 9999;
   }

   MetricType metric_type = 5;

   // A container for enumerated sets of event codes.
   message MetricDimension {
     // Name of the dimension. Used only in the generated library for the names
     // of the constants.
     string dimension = 1;

     // The enumerated set of event codes for this dimension.
     //
     // The keys are the numeric codes and the values are the
     // human-readable labels for the codes. It is OK to add new elements to this
     // map or to change the spelling of labels after data collection has
     // started. It is not OK to change the meaning of any of the codes.
     //
     // If an event code for a dimension is not passed to the Cobalt logger for
     // an event that occurred, the value zero will be used. Therefore, it is
     // not recommended to associate the zero event code with a meaningful
     // label. Instead, omit the zero event code and your reports will contain
     // event code labels of `<code 0>` when the event code was not specified,
     // or specify an explict zero value with a label of `Unknown` or `Unset`.
     map<uint32, string> event_codes = 2;

     // max_event_code is the maximal value for any event in this dimension.
     // Subject to the following rules:
     //
     // 1. If you specify max_event_code, you cannot use a value greater than
     //    that.
     // 2. If you do not specify max_event_code, you can only use one of the
     //    explicitly registered values (event_codes).
     // 3. For the purposes of validation, each dimension is assigned a number
     //    which is equal to max_event_code+1 if max_event_code is set, or else
     //    equal to the number of registered values. The product of all of these
     //    values must not exceed 1024.
     // 4. Adding, removing, or changing max_event_code is allowed so long as the
     //    above rules are not violated.
     // 5. For metrics of the type EVENT_OCCURRED, there may be only 1 dimension.
     uint32 max_event_code = 3;

     reserved 4;
     reserved "also_treat_as_legacy";

     // event_code_aliases is used by the code generator to generate additional
     // enum variants. This is intended as a temporary step to allow a soft
     // cross-repo rename of an event_code variant, and should be cleaned up as
     // soon as possible.
     //
     // The expected use case is as follows (config abbridged for clarity):
     //
     // Step 1: Have a metric
     //
     //   event_codes:
     //     - 1: BadName
     //
     // Step 2: Rename an event code, adding an alias
     //
     //   event_codes:
     //     - 1: GoodName
     //   event_code_aliases:
     //     GoodName: BadName
     //
     // Step 3: After all references to `BadName` are removed
     //
     //   event_codes:
     //     - 1: GoodName
     //
     map<string, string> event_code_aliases = 5;
   }

   // A list of MetricDimensions.
   //
   // This field is used in most Metric types.
   repeated MetricDimension metric_dimensions = 16;

   // For metrics of types INTEGER and INTEGER_HISTOGRAM, specifies the units of
   // the integer. Either metric_units or metric_units_other must be specified.
   // Use metric_units_other if none of the pre-defined MetricUnits are
   // appropriate.
   MetricUnits metric_units = 18;
   string metric_units_other = 19;

   // Specifies a list of pre-defined semantic categories for the metric.
   // This should augment the description given in the comments.
   repeated MetricSemantics metric_semantics = 20;

   // The maximum number of distinct strings that Cobalt must
   // keep in its in-memory buffer on any single device.
   // During local aggregation for metrics of type STRING, Cobalt will keep track
   // of this many distinct strings per aggregation period. The metric's project
   // will be charged against a resource budget for this value so project owners
   // are encouraged to set this as small as possible. A STRING metric
   // includes a file of candidate strings that may contain many thousands
   // of strings. But it is expected that any one device will log only a few of
   // these strings per day. We may set string_buffer_max to a relatively
   // small number, say 20.
   //
   // This is a required field for metrics of type STRING.
   uint32 string_buffer_max = 21;

   // The path to a list of candidate strings for a metric of type STRING.
   //
   // This is a required field for metrics of type STRING.
   string string_candidate_file = 22;

   // The set of buckets for the histograms for this metric. This field is used
   // only with metrics of type INT_HISTOGRAM (in Cobalt 1.0) and
   // INTEGER_HISTOGRAM (in Cobalt 1.1.)
   IntegerBuckets int_buckets = 8;

   // Used only with metric_type = CUSTOM
   // The fully qualified name of the underlying proto used for custom metrics.
   string proto_name = 13;

   /////////// The rest of the fields are used with all Metric types ///////////

   // A TimeZonePolicy specifies how the day index of an Event should be computed
   // based on the system time when the Event is logged.
   enum TimeZonePolicy {
     // Use the date in UTC at logging time to compute the day index.
     UTC = 0;

     // Use the device-local date at logging time to compute the day index.
     LOCAL = 1;

     // Use the time zone specified in the `other_time_zone` field to compute the
     // day index.
     OTHER_TIME_ZONE = 2;
   }

   // The TimeZonePolicy for this Metric (Optional. Defaults to UTC)
   TimeZonePolicy time_zone_policy = 10;

   // An IANA time zone identifier (https://iana.org/time-zones). Should be set if
   // and only if the metric's `time_zone_policy` is OTHER_TIME_ZONE.
   string other_time_zone = 25;

   message Metadata {
     // The date 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.
     //
     // The date must be expressed in yyyy/mm/dd form.
     // It may be at most one year in the future.
     string expiration_date = 1 [(cobalt_options).hide_on_client = true];

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

     // Maximum ReleaseStage for which this Metric is allowed to be collected.
     ReleaseStage max_release_stage = 4;

     // If 'also_log_locally' is true, Cobalt will log it when it receives events
     // associated with this metric.
     bool also_log_locally = 5;
   }
   Metadata meta_data = 11;

   // The Reports to run for this Metric.
   repeated ReportDefinition reports = 12;
 }

 // Stages in the release cycle of a component. Each Cobalt project declares
 // its current ReleaseStage in its ProjectContext. Each Metric declares
 // the maximum ReleaseStage for which it is allowed to be collected.
 // For example a DEBUG Metric will not be collected in a FISHFOOD release .
 enum ReleaseStage {
   RELEASE_STAGE_NOT_SET = 0;

   DEBUG = 10;
   FISHFOOD = 20;
   DOGFOOD = 40;

   // Generally-available
   GA = 99;
 }

 enum MetricUnits {
   METRIC_UNITS_OTHER = 0;

   // Units of time
   NANOSECONDS = 1;
   MICROSECONDS = 2;
   MILLISECONDS = 3;
   SECONDS = 4;
   MINUTES = 5;

   // Units of data size
   BYTES = 6;
   KIBIBYTES = 7;   // 2^10 bytes
   KILOBYTES = 8;   // 10^3 bytes
   MEBIBYTES = 9;   // 2^20 bytes
   MEGABYTES = 10;  // 10^6 bytes
 }

 enum MetricSemantics {
   METRIC_SEMANTICS_UNSPECIFIED = 0;

   // The metric measure how much CPU is being used.
   CPU = 1;

   // The metric measures size of a data structure.
   DATA_SIZE = 2;

   // The metric measures frame rendering performance.
   FRAME_RENDERING = 3;

   // The metric measures the latency of an operation.
   LATENCY = 4;

   // The metric measures the amount of memory being used.
   MEMORY_USAGE = 5;

   // The metric measures something about the devices network communication.
   NETWORK_COMMUNICATION = 6;

   // The metric is being used to measure some property of the real world
   // environment outside of the device.
   OUTSIDE_ENVIRONMENT = 7;

   // The metric is being used to track how often a feature or system is used.
   USAGE_COUNTING = 8;
 }
	// Copyright 2018 The Fuchsia Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style license that can be
	// found in the LICENSE file.
	syntax = "proto3";

	package cobalt;

	import "src/registry/annotations.proto";
	import "src/registry/report_definition.proto";

	option go_package = "src/registry;config";

	// A Metric is a category of Events that a user logs to Cobalt.
	//
	// A Metric belongs to a Project and has a name and a type.
	//
	// When an Event is logged in Cobalt's Logger interface, a Metric is
	// specified and the Event then belongs to that Metric.
	//
	// A MetricDefinition includes a list of ReportDefinitions. These are the
	// definitions of the Reports that should be run for that Metric. Generating a
	// Report involves the Cobalt client sending Observations to the server based
	// on the Events belonging to the Metric, and the server performing an analysis
	// of those Observations in order to generate the Report output.
	//
	// When an Observation is sent from a Cobalt client to the server, it contains
	// a Metric id and a Report id. This indicates that the
	// Observation is derived from the Events belonging to the Metric for the
	// purpose of generating the Report.
	//
	// A MetricDefinition is used to define a Metric.
	//
	// Next ID: 26
	message MetricDefinition {
	reserved 6, 7, 9, 17;
	reserved "event_codes", "max_event_code", "parts", "event_code_buffer_max";

	// Unique name for this Metric within its owning project.
	// The name must obey the syntax of a C variable name and must have length
	// at most 64.
	string metric_name = 1;

	// The Cobalt registry YAML parser will automatically set the values of
	// customer_name and project_name based on the context of the YAML file.
	string customer_name = 14 [(cobalt_options).hide_on_client = true];
	string project_name = 15 [(cobalt_options).hide_on_client = true];

	// These three numbers form this Metric's unique numerical ID in Cobalt. The
	// Cobalt registry YAML parser will automatically set the value of
	// customer_id and project_id based on the context of the YAML file.
	// The user must manually set the \|id\| field to a number uniquely identifying
	// this Metric within its project.
	uint32 customer_id = 2;
	uint32 project_id = 3;
	uint32 id = 4;

	// This field should only be used for migrating a Cobalt 1.0 metric to a Cobalt 1.1 metric. Any
	// events that are logged to this metric will be mirrored to replacement_metric. This field should
	// be set only on 1.0 metrics, and include the metric_id of the replacement 1.1 metric.
	uint32 replacement_metric_id = 23;
	// This field should be used to document why a metric is not being migrated to Cobalt 1.1.
	string no_replacement_metric = 24 [(cobalt_options).hide_on_client = true];

	// A Metric has one of the following types.
	// Next ID: 12
	enum MetricType {
	reserved 7;
	reserved "STRING_USED";

	UNSET = 0;

	// Records that an event has occurred.
	//
	// Event fields:
	// - uint32 event_code # The event_code for the event that occurred.
	//
	// MetricDefinition fields:
	// - event_codes # Enumerated list of all possible event types
	// - metric_dimensions # Extra user-defined dimensions for this metric. Each
	// dimension consists of an enumerated set of event
	// codes. (For metrics of type EVENT_OCCURRED there
	// must be exactly one).
	// - max_num_event_codes # Upper bound on future growth of event_codes
	//
	// Compatible report types:
	// - SIMPLE_OCCURRENCE_COUNT
	// - UNIQUE_N_DAY_ACTIVES
	//
	// TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
	EVENT_OCCURRED = 1;

	// Records that an event occurred a number of times.
	//
	// Event fields:
	// - repeated uint32 event_code # The event codes for the event that
	// occurred. There must be one event code
	// given for each dimension specified in the
	// metric definition.
	// - string component # The associated system component
	// - int64 period_duration_micros # Time over which the count was taken
	// - uint32 count # The number of times the event occurred.
	//
	// MetricDefinition fields:
	// - event_codes # Enumerated list of all possible event types
	// - metric_dimensions # Extra user-defined dimensions for this metric. Each
	// dimension consists of an enumerated set of event
	// codes.
	//
	// Compatible report types:
	// - EVENT_COMPONENT_OCCURRENCE_COUNT
	// - INT_RANGE_HISTOGRAM
	// - NUMERIC_AGGREGATION
	// - PER_DEVICE_NUMERIC_STATS
	// - PER_DEVICE_HISTOGRAM
	//
	// TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
	EVENT_COUNT = 2;

	// Records an elapsed time.
	//
	// Event fields:
	// - repeated uint32 event_code # The event codes for the event that
	// occurred. There must be one event code
	// given for each dimension specified in the
	// metric definition.
	// - string component # The associated system component
	// - int64 elapsed_micros # The elapsed time in microseconds.
	//
	// MetricDefinition fields:
	// - event_codes # Enumerated list of all possible event types
	// - metric_dimensions # Extra user-defined dimensions for this metric. Each
	// dimension consists of an enumerated set of event
	// codes.
	//
	// Compatible report types:
	// - NUMERIC_AGGREGATION
	// - INT_RANGE_HISTOGRAM
	// - PER_DEVICE_NUMERIC_STATS
	// - PER_DEVICE_HISTOGRAM
	//
	// TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
	ELAPSED_TIME = 3;

	// Records a frame-rate.
	//
	// Event fields:
	// - repeated uint32 event_code # The event codes for the event that
	// occurred. There must be one event code
	// given for each dimension specified in the
	// metric definition.
	// - string component # The associated system component
	// - int32 frame_rate # round(frames-per-second * 1000)
	//
	// MetricDefinition fields:
	// - event_codes # Enumerated list of all possible event types
	// - metric_dimensions # Extra user-defined dimensions for this metric. Each
	// dimension consists of an enumerated set of event
	// codes.
	//
	// Compatible report types:
	// - NUMERIC_AGGREGATION
	// - INT_RANGE_HISTOGRAM
	// - PER_DEVICE_NUMERIC_STATS
	// - PER_DEVICE_HISTOGRAM
	//
	// TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
	FRAME_RATE = 4;

	// Records a memory-usage.
	//
	// Event fields:
	// - repeated uint32 event_code # The event codes for the event that
	// occurred. There must be one event code
	// given for each dimension specified in the
	// metric definition.
	// - string component # The associated system component
	// - int64 bytes # Memory usage in bytes.
	//
	// MetricDefinition fields:
	// - event_codes # Enumerated list of all possible event types
	// - metric_dimensions # Extra user-defined dimensions for this metric. Each
	// dimension consists of an enumerated set of event
	// codes.
	//
	// Compatible report types:
	// - NUMERIC_AGGREGATION
	// - INT_RANGE_HISTOGRAM
	// - PER_DEVICE_NUMERIC_STATS
	// - PER_DEVICE_HISTOGRAM
	//
	// TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
	MEMORY_USAGE = 5;

	// Records a histogram over a set of integer buckets. The semantics of the
	// Metric must be specified in comments near the Metric definition. The
	// numerical values of the buckets is specified below in the \|int_buckets\|
	// field.
	//
	// This Metric type is intended to be used in situations where the client
	// wishes to aggregate a large number of integer-valued measurements
	// in-process, prior to submitting the data to Cobalt.
	//
	// Event fields:
	// - repeated uint32 event_code # The event codes for the event that
	// occurred. There must be one event code
	// given for each dimension specified in the
	// metric definition.
	// - string component # The associated system component
	// - vector<HistogramBucket> histogram # The histogram being logged.
	//
	// MetricDefinition fields:
	// - int_buckets # The definition of the buckets
	// - event_codes # Enumerated list of all possible event types
	// - metric_dimensions # Extra user-defined dimensions for this metric. Each
	// dimension consists of an enumerated set of event
	// codes.
	//
	// Compatible report types:
	// - INT_RANGE_HISTOGRAM
	//
	// TODO(fxbug.dev/45463): Delete when all users move to Cobalt 1.1.
	INT_HISTOGRAM = 6;

	// Records that an event has occurred one or many times.
	//
	// MetricDefinition fields:
	// - metric_dimensions (0 or more)
	// - metric_semantics (required)
	OCCURRENCE = 8;

	// Records an integer measurement.
	//
	// MetricDefinition fields:
	// - metric_dimensions (0 or more)
	// - metric_units (Either this field or metric_units_other is required.)
	// - metric_units_other (Either metric_units or this field is required.)
	// - metric_semantics (required)
	INTEGER = 9;

	// Records many approximate integer measurements.
	//
	// MetricDefinition fields:
	// - metric_dimensions (0 or more)
	// - int_buckets
	// - metric_units (Either this field or metric_units other is required.)
	// - metric_units_other (Either metric_units or this field is required.)
	// - metric_semantics (required)
	INTEGER_HISTOGRAM = 10;

	// Records the fact that a string was observed.
	//
	// MetricDefinition fields:
	// - metric_dimensions (0 or more)
	// - metric_semantics (required)
	// - string_candidate_file. (required)
	// - string_buffer_max (required)
	STRING = 11;

	// Allows users of Cobalt to define custom Metrics with custom semantics and
	// their own data type. A metric of this type is associated with a protocol
	// buffer definition and proto messages of that type will be populated with
	// the data logged for this metric. The semantics of the Metric should be
	// specified in the .proto file. Each event logged for this Metric must have
	// dimensions with names and types that correspond to the fields of the
	// associated proto or the serialized proto itself.
	//
	// Event fields:
	// vector<CustomEventValue> event_values # Named, typed values
	//
	// MetricDefinition fields:
	// - proto_name # The fully qualified name of the protobuf associated with
	// this Metric.
	//
	// Compatible report types:
	// - CUSTOM_RAW_DUMP
	CUSTOM = 9999;
	}

	MetricType metric_type = 5;

	// A container for enumerated sets of event codes.
	message MetricDimension {
	// Name of the dimension. Used only in the generated library for the names
	// of the constants.
	string dimension = 1;

	// The enumerated set of event codes for this dimension.
	//
	// The keys are the numeric codes and the values are the
	// human-readable labels for the codes. It is OK to add new elements to this
	// map or to change the spelling of labels after data collection has
	// started. It is not OK to change the meaning of any of the codes.
	//
	// If an event code for a dimension is not passed to the Cobalt logger for
	// an event that occurred, the value zero will be used. Therefore, it is
	// not recommended to associate the zero event code with a meaningful
	// label. Instead, omit the zero event code and your reports will contain
	// event code labels of `<code 0>` when the event code was not specified,
	// or specify an explict zero value with a label of `Unknown` or `Unset`.
	map<uint32, string> event_codes = 2;

	// max_event_code is the maximal value for any event in this dimension.
	// Subject to the following rules:
	//
	// 1. If you specify max_event_code, you cannot use a value greater than
	// that.
	// 2. If you do not specify max_event_code, you can only use one of the
	// explicitly registered values (event_codes).
	// 3. For the purposes of validation, each dimension is assigned a number
	// which is equal to max_event_code+1 if max_event_code is set, or else
	// equal to the number of registered values. The product of all of these
	// values must not exceed 1024.
	// 4. Adding, removing, or changing max_event_code is allowed so long as the
	// above rules are not violated.
	// 5. For metrics of the type EVENT_OCCURRED, there may be only 1 dimension.
	uint32 max_event_code = 3;

	reserved 4;
	reserved "also_treat_as_legacy";

	// event_code_aliases is used by the code generator to generate additional
	// enum variants. This is intended as a temporary step to allow a soft
	// cross-repo rename of an event_code variant, and should be cleaned up as
	// soon as possible.
	//
	// The expected use case is as follows (config abbridged for clarity):
	//
	// Step 1: Have a metric
	//
	// event_codes:
	// - 1: BadName
	//
	// Step 2: Rename an event code, adding an alias
	//
	// event_codes:
	// - 1: GoodName
	// event_code_aliases:
	// GoodName: BadName
	//
	// Step 3: After all references to `BadName` are removed
	//
	// event_codes:
	// - 1: GoodName
	//
	map<string, string> event_code_aliases = 5;
	}

	// A list of MetricDimensions.
	//
	// This field is used in most Metric types.
	repeated MetricDimension metric_dimensions = 16;

	// For metrics of types INTEGER and INTEGER_HISTOGRAM, specifies the units of
	// the integer. Either metric_units or metric_units_other must be specified.
	// Use metric_units_other if none of the pre-defined MetricUnits are
	// appropriate.
	MetricUnits metric_units = 18;
	string metric_units_other = 19;

	// Specifies a list of pre-defined semantic categories for the metric.
	// This should augment the description given in the comments.
	repeated MetricSemantics metric_semantics = 20;

	// The maximum number of distinct strings that Cobalt must
	// keep in its in-memory buffer on any single device.
	// During local aggregation for metrics of type STRING, Cobalt will keep track
	// of this many distinct strings per aggregation period. The metric's project
	// will be charged against a resource budget for this value so project owners
	// are encouraged to set this as small as possible. A STRING metric
	// includes a file of candidate strings that may contain many thousands
	// of strings. But it is expected that any one device will log only a few of
	// these strings per day. We may set string_buffer_max to a relatively
	// small number, say 20.
	//
	// This is a required field for metrics of type STRING.
	uint32 string_buffer_max = 21;

	// The path to a list of candidate strings for a metric of type STRING.
	//
	// This is a required field for metrics of type STRING.
	string string_candidate_file = 22;

	// The set of buckets for the histograms for this metric. This field is used
	// only with metrics of type INT_HISTOGRAM (in Cobalt 1.0) and
	// INTEGER_HISTOGRAM (in Cobalt 1.1.)
	IntegerBuckets int_buckets = 8;

	// Used only with metric_type = CUSTOM
	// The fully qualified name of the underlying proto used for custom metrics.
	string proto_name = 13;

	/////////// The rest of the fields are used with all Metric types ///////////

	// A TimeZonePolicy specifies how the day index of an Event should be computed
	// based on the system time when the Event is logged.
	enum TimeZonePolicy {
	// Use the date in UTC at logging time to compute the day index.
	UTC = 0;

	// Use the device-local date at logging time to compute the day index.
	LOCAL = 1;

	// Use the time zone specified in the `other_time_zone` field to compute the
	// day index.
	OTHER_TIME_ZONE = 2;
	}

	// The TimeZonePolicy for this Metric (Optional. Defaults to UTC)
	TimeZonePolicy time_zone_policy = 10;

	// An IANA time zone identifier (https://iana.org/time-zones). Should be set if
	// and only if the metric's `time_zone_policy` is OTHER_TIME_ZONE.
	string other_time_zone = 25;

	message Metadata {
	// The date 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.
	//
	// The date must be expressed in yyyy/mm/dd form.
	// It may be at most one year in the future.
	string expiration_date = 1 [(cobalt_options).hide_on_client = true];

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

	// Maximum ReleaseStage for which this Metric is allowed to be collected.
	ReleaseStage max_release_stage = 4;

	// If 'also_log_locally' is true, Cobalt will log it when it receives events
	// associated with this metric.
	bool also_log_locally = 5;
	}
	Metadata meta_data = 11;

	// The Reports to run for this Metric.
	repeated ReportDefinition reports = 12;
	}

	// Stages in the release cycle of a component. Each Cobalt project declares
	// its current ReleaseStage in its ProjectContext. Each Metric declares
	// the maximum ReleaseStage for which it is allowed to be collected.
	// For example a DEBUG Metric will not be collected in a FISHFOOD release .
	enum ReleaseStage {
	RELEASE_STAGE_NOT_SET = 0;

	DEBUG = 10;
	FISHFOOD = 20;
	DOGFOOD = 40;

	// Generally-available
	GA = 99;
	}

	enum MetricUnits {
	METRIC_UNITS_OTHER = 0;

	// Units of time
	NANOSECONDS = 1;
	MICROSECONDS = 2;
	MILLISECONDS = 3;
	SECONDS = 4;
	MINUTES = 5;

	// Units of data size
	BYTES = 6;
	KIBIBYTES = 7; // 2^10 bytes
	KILOBYTES = 8; // 10^3 bytes
	MEBIBYTES = 9; // 2^20 bytes
	MEGABYTES = 10; // 10^6 bytes
	}

	enum MetricSemantics {
	METRIC_SEMANTICS_UNSPECIFIED = 0;

	// The metric measure how much CPU is being used.
	CPU = 1;

	// The metric measures size of a data structure.
	DATA_SIZE = 2;

	// The metric measures frame rendering performance.
	FRAME_RENDERING = 3;

	// The metric measures the latency of an operation.
	LATENCY = 4;

	// The metric measures the amount of memory being used.
	MEMORY_USAGE = 5;

	// The metric measures something about the devices network communication.
	NETWORK_COMMUNICATION = 6;

	// The metric is being used to measure some property of the real world
	// environment outside of the device.
	OUTSIDE_ENVIRONMENT = 7;

	// The metric is being used to track how often a feature or system is used.
	USAGE_COUNTING = 8;
	}