| // 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: 23 |
| message MetricDefinition { |
| reserved 6, 7; |
| reserved "event_codes", "max_event_code"; |
| |
| // 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; |
| |
| // 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(fxb/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(fxb/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(fxb/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(fxb/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(fxb/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(fxb/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) |
| // - event_code_buffer_max (optional, defaults to total number of event vectors) |
| // - metric_semantics (required) |
| // |
| // This metric type is part of Cobalt 1.1. Do not use it yet. |
| OCCURRENCE = 8; |
| |
| // Records an integer measurement. |
| // |
| // MetricDefinition fields: |
| // - metric_dimensions (0 or more) |
| // - event_code_buffer_max (optional, defaults to total number of event vectors) |
| // - 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) |
| // |
| // This metric type is part of Cobalt 1.1. Do not use it yet. |
| INTEGER = 9; |
| |
| // Records many approximate integer measurements. |
| // |
| // MetricDefinition fields: |
| // - metric_dimensions (0 or more) |
| // - event_code_buffer_max (optional, defaults to total number of event vectors) |
| // - 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) |
| // |
| // This metric type is part of Cobalt 1.1. Do not use it yet. |
| INTEGER_HISTOGRAM = 10; |
| |
| // Records the fact that a string was observed. |
| // |
| // MetricDefinition fields: |
| // - metric_dimensions (0 or more) |
| // - event_code_buffer_max (optional, defaults to total number of event vectors) |
| // - metric_semantics (required) |
| // - string_candidate_file. (required) |
| // - string_buffer_max (required) |
| // |
| // This metric type is part of Cobalt 1.1. Do not use it yet. |
| STRING = 11; |
| |
| // Allows users of Cobalt to define custom Metrics with custom semantics and |
| // multiple parts, each with 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 and its parts should be specified in the .proto |
| // file. Each event logged for this Metric must have parts with names and |
| // types that corresponding to the fields of the associated proto. |
| // |
| // 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 { |
| 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. |
| 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: |
| // - 0: BadName |
| // |
| // Step 2: Rename an event code, adding an alias |
| // |
| // event_codes: |
| // - 0: GoodName |
| // event_code_aliases: |
| // GoodName: BadName |
| // |
| // Step 3: After all references to `BadName` are removed |
| // |
| // event_codes: |
| // - 0: 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; |
| |
| // The maximum number of distinct event vectors for which an instance |
| // of the Cobalt client should produce an observation, for a given |
| // local aggregation period. Event vectors are prioritized in order of |
| // first arrival during the aggregation period. |
| // |
| // For example, if a metric has an event_code_buffer_max of 10, and 12 |
| // distinct event vectors are logged for this metric over an aggregation |
| // period, then Cobalt will send observations of the first 10 event vectors |
| // for that aggregation period and drop the last 2. |
| // |
| // 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. |
| // For example, the metric may include a metric dimension with thousands of |
| // event codes, but it is expected that any one device will log only a few |
| // of these event_codes per day. We may set event_code_buffer_max to a |
| // relatively small number, say 20. For reports which use differential |
| // privacy, setting event_code_buffer_max to a smaller number will improve |
| // the signal for event vectors which are included in observations. |
| // |
| // This field is part of Cobalt 1.1. Do not use it yet. |
| uint64 event_code_buffer_max = 17; |
| |
| // 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. |
| // |
| // These fields are part of Cobalt 1.1. Do not use them yet. |
| 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 field is part of Cobalt 1.1. Do not use it yet. |
| // It 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 field is part of Cobalt 1.1. Do not use it yet. |
| // It 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 keys are the names of the parts. |
| map<string, MetricPart> parts = 9 [deprecated = true]; |
| |
| // 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 actual time of logging. |
| enum TimeZonePolicy { |
| // Use the date in UTC at logging time to compute the day_index. |
| UTC = 0; |
| |
| // Use the local date at logging time to compute the day_index. |
| LOCAL = 1; |
| } |
| |
| // The TimeZonePolicy for this Metric (Optional. Defaults to UTC) |
| TimeZonePolicy time_zone_policy = 10; |
| |
| 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; |
| } |
| |
| // For mertics of type = CUSTOM, a metric may have zero or more |string| to |MetricPart| mappings, |
| // that will be used when encoding an event. |
| // |
| // NOTE: This method of reporting custom metrics is now deprecated. |
| 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; |
| } |