// 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";
import "config/annotations.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 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: 17
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.
  string metric_name = 1;

  // The Cobalt config 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 config 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: 8
  enum MetricType {
    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
    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
    // - PER_DEVICE_COUNT_STATS
    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
    // - NUMERIC_PERF_RAW_DUMP
    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
    // - NUMERIC_PERF_RAW_DUMP
    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
    // - 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:
    // - 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
    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. 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 (+1 if there is no zero
    //    value). 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;

    // Enables soft transitions in the source_generator. Will generate enums for
    // this dimension, as well as enums as if this was a legacy event_codes map.
    // This is only a temporary field, and will only work properly if there is
    // only one dimension with this field set.  TODO(zmbush): Remove once
    // metric_dimension migration is complete.
    bool also_treat_as_legacy = 4;
  }

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

  // The enumerated set of event codes.
  //
  // This field is used in most Metric types.
  //
  // 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 = 6
      [(cobalt_options).hide_on_client = true, deprecated = true];

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

// A container for multiple MetricDefinitions.
message MetricDefinitions {
  repeated MetricDefinition metric = 1;
}