| // 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 "config/metrics.proto"; |
| import "config/report_definition.proto"; |
| |
| option go_package = "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 name 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. |
| message MetricDefinition { |
| // 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. The name must not be changed once data collection has |
| // begun. Changing the name constitutes declaring a different Metric. |
| string metric_name = 1; |
| |
| // These three numbers form this Metric's unique numerical ID, used internally |
| // by Cobalt. Normally an instance of MetricDefinition is created by the |
| // Cobalt config YAML parser and these three values will be set automatically. |
| // None of these three values need to be manually set in the YAML file. The |
| // customer_id and project_id are known from the context of the YAML file and |
| // the |id| is set to a hash of the |name| field above. If an instance of |
| // MetricDefinition is created by some means other than the YAML parser |
| // then these values must be set. The |id| field should be set 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. |
| enum MetricType { |
| UNSET = 0; |
| |
| // Records that an event has occurred. |
| // |
| // Event fields: |
| // - uint32 event_code # The index of the event type that occurred. |
| // |
| // MetricDefinition fields: |
| // - event_codes # Enumerated list of all possible event types |
| // - max_num_event_codes # Upper bound on future growth of event_codes |
| // |
| // Compatible report types: |
| // - SIMPLE_OCCURRENCE_COUNT |
| EVENT_OCCURRED = 1; |
| |
| // Records that an event occurred a number of times. |
| // |
| // Event fields: |
| // - uint32 event_code # The index of the event type that occurred. |
| // - 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 |
| // |
| // Compatible report types: |
| // - EVENT_COMPONENT_OCCURRENCE_COUNT |
| EVENT_COUNT = 2; |
| |
| // Records an elapsed time. |
| // |
| // Event fields: |
| // - uint32 event_code # The index of the event type that occurred. |
| // - 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 |
| // |
| // Compatible report types: |
| // - NUMERIC_AGGREGATION |
| // - INT_RANGE_HISTOGRAM |
| // - NUMERIC_PERF_RAW_DUMP |
| ELAPSED_TIME = 3; |
| |
| // Records a frame-rate. |
| // |
| // Event fields: |
| // - uint32 event_code # The index of the event type that occurred. |
| // - 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 |
| // |
| // Compatible report types: |
| // - NUMERIC_AGGREGATION |
| // - INT_RANGE_HISTOGRAM |
| // - NUMERIC_PERF_RAW_DUMP |
| FRAME_RATE = 4; |
| |
| // Records a memory-usage. |
| // |
| // Event fields: |
| // - uint32 event_code # The index of the event type that occurred. |
| // - string component # The associated system component |
| // - int64 bytes # Memory usage in bytes. |
| // |
| // MetricDefinition fields: |
| // - event_codes # Enumerated list of all possible event types |
| // |
| // Compatible report types: |
| // - NUMERIC_AGGREGATION |
| // - INT_RANGE_HISTOGRAM |
| // - NUMERIC_PERF_RAW_DUMP |
| 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: |
| // - uint32 event_code # The index of the event type that occurred. |
| // - 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 |
| // |
| // Compatible report types: |
| // - INT_RANGE_HISTOGRAM |
| INT_HISTOGRAM = 6; |
| |
| // Records that a given string was used in a specific context. The semantics |
| // of the Metric must be specified in comments near the MetricDefintion. |
| // |
| // This metric type is intended to be used in the following situation: |
| // * The string being logged does not contain PII or passwords. |
| // * The set of all possible strings that may be logged is large. |
| // If the set is small consider using EVENT_OCCURED instead. |
| // * The ultimate data of interest is the statistical distribution of the |
| // most commonly used strings |
| // |
| // Event fields: |
| // - string s # The string that was used. |
| // |
| // MetricDefinition fields: None |
| // |
| // Compatible report types: |
| // - HIGH_FREQUENCY_STRING_COUNTS |
| // - STRING_COUNTS_WITH_THRESHOLD |
| STRING_USED = 7; |
| |
| // Allows users of Cobalt to define custom Metrics with custom semantics |
| // and multiple parts each with their own data type. The semantics of the |
| // Metric as a whole and of each part must be specified in comments. |
| // |
| // Event fields: |
| // vector<CustomEventValue> event_values # Named, typed values |
| // |
| // MetricDefinition fields: |
| // - parts # The definition of the names and types of the parts. |
| // |
| // Compatible report types: |
| // - CUSTOM_RAW_DUMP |
| CUSTOM = 9999; |
| } |
| |
| MetricType metric_type = 5; |
| |
| // The enumerated set of event types for the event_code parameter. |
| // |
| // This field is used in most Metric types. |
| // |
| // The keys are the indices and the values are the human-readable names of |
| // the event types. It is OK to add new elements to this map or to change |
| // the spelling of event names after data collection has |
| // started. It is not OK to change the meaning of any of the indices. |
| // ##DO_NOT_POPULATE_ON_CLIENT## |
| map<uint32, string> event_codes = 6; |
| |
| // Only needed with Metrics of type EVENT_OCCURRED. |
| // While additional event_codes may be added after data collection has begun, |
| // this value may not be changed and the event type indices must not exceed |
| // this value. Leave room for future growth of event_codes but set |
| // as small as possible because this affects the size of the Observations |
| // sent to the server for this Metric. This value must be < 1024. |
| uint32 max_event_code = 7; |
| |
| // The set of buckets for the histograms for this metric. This field is used |
| // only with metrics of type INT_HISTOGRAM |
| IntegerBuckets int_buckets = 8; |
| |
| // Used only with metric_type = CUSTOM |
| // The keys are the names of the parts. |
| map<string, MetricPart> parts = 9; |
| |
| /////////// 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; |
| |
| // 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; |
| |
| // Maximum ReleaseStage for which this Metric is allowed to be collected. |
| ReleaseStage max_release_stage = 4; |
| } |
| 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; |
| } |
| |
| // A container for multiple MetricDefinitions. |
| message MetricDefinitions { |
| repeated MetricDefinition metric = 1; |
| } |