// 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: 25
message MetricDefinition {
  reserved 6, 7, 9;
  reserved "event_codes", "max_event_code", "parts";

  // 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(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)
    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)
    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)
    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)
    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.
    //
    // 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;

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