src/registry/metric_definition.proto

// 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/report_definition.proto";

option go_package = "src/registry;config";

// Defines a Metric, which represents a type of Events logged to Cobalt.
//
// Each Metric belongs to a specific Project and is identified by a unique name
// and ID within that project. Metrics have a defined type (e.g., OCCURRENCE,
// INTEGER) which dictates the value logged as part of the event.
//
// When an Event is logged via the Cobalt Logger interface, it's associated with
// a specific Metric.
//
// A MetricDefinition also contains a list of ReportDefinitions. These specify
// the aggregations to be performed on the data logged to this Metric.
// Generating a Report involves Observations (derived from the Metric's Events)
// being sent from the Cobalt client to the server for analysis. Each
// Observation includes the Metric ID and Report ID it pertains to.
// Next ID: 28
message MetricDefinition {
  reserved 6, 7, 9, 13, 14, 15, 17, 21, 23, 24;
  reserved "event_codes", "event_code_buffer_max", "max_event_code", "parts", "proto_name",
      "string_buffer_max", "replacement_metric_id", "no_replacement_metric", "customer_name",
      "project_name";

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

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

  // Specifies the type of the Metric. The type determines the nature of the
  // data collected and the relevant fields within MetricDefinition.
  // Next ID: 13
  enum MetricType {
    reserved 1, 2, 3, 4, 5, 6, 7, 9999;
    reserved "CUSTOM", "ELAPSED_TIME", "EVENT_COUNT", "EVENT_OCCURRED", "FRAME_RATE",
        "INT_HISTOGRAM", "MEMORY_USAGE", "STRING_USED";

    UNSET = 0;

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

    // Records a single integer measurement.
    //
    // Relevant MetricDefinition fields:
    // - metric_dimensions (0 or more)
    // - metric_units or metric_units_other (either field is required)
    // - metric_semantics (required)
    INTEGER = 9;

    // Records a distribution of integer measurements using buckets.
    //
    // Relevant MetricDefinition fields:
    // - metric_dimensions (0 or more)
    // - int_buckets (required)
    // - metric_units or metric_units_other (either field is required)
    // - metric_semantics (required)
    INTEGER_HISTOGRAM = 10;

    // Records the occurrence of a specific string value.
    //
    // Relevant MetricDefinition fields:
    // - metric_dimensions (0 or more)
    // - metric_semantics (required)
    // - string_candidate_file (required)
    STRING = 11;

    // Experimental. DO NOT USE!
    // Records an instance of a defined structure.
    //
    // MetricDefinition fields:
    // - struct_fields (optional):
    STRUCT = 12;
  }

  MetricType metric_type = 5;

  // Defines a dimension for a Metric, allowing Events to be categorized using
  // enumerated 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.
    //
    // Keys are the numeric codes, and values are their human-readable labels.
    // It's safe to add new codes or change labels after data collection starts,
    // but the semantic meaning of existing codes must not change.
    //
    // If an event code for a dimension isn't provided during logging, the value
    // 0 (zero) is used by default. It's recommended to either:
    // a) Omit the zero code entirely (reports will show `<code 0>`).
    // b) Explicitly define code 0 with a label like `Unknown` or `Unset`.
    map<uint32, string> event_codes = 2;

    // This field should only be used if a customer is using differential
    // privacy or they aren't listing an event code. For example, to log numbers
    // between 0 and 19 without names.
    // The maximum allowed value for an event code in this dimension.
    // The following rules apply when differential privacy is involved:
    // 1. If set, logged event codes cannot exceed this value.
    // 2. If not set, only explicitly defined codes in `event_codes` are allowed.
    // 3. Validation check: For each dimension, calculate a size (max_event_code + 1
    //    if set, otherwise the count of defined event_codes). The product of
    //    these sizes across all dimensions of a metric must not exceed 1024.
    // 4. This value can be added, removed, or changed later, provided the above
    //    rules are maintained.
    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 dimensions used to categorize events for this Metric.
  // Used by OCCURRENCE, INTEGER, INTEGER_HISTOGRAM, and STRING metric types.
  repeated MetricDimension metric_dimensions = 16;

  // For INTEGER and INTEGER_HISTOGRAM metrics, specifies the units of the
  // integer values. Use `metric_units` for predefined units or
  // `metric_units_other` for custom units. One of these fields is required
  // for these metric types.
  MetricUnits metric_units = 18;
  string metric_units_other = 19;

  // A list of predefined semantic categories describing the metric's purpose.
  // This complements the textual description and is required for OCCURRENCE,
  // INTEGER, INTEGER_HISTOGRAM, and STRING metric types.
  repeated MetricSemantics metric_semantics = 20;

  // Path to a file containing a list of candidate strings.
  // Required for metrics of type STRING. The path should be relative to the
  // Cobalt registry root (e.g., "$CUSTOMER/$PROJECT/candidate_strings.txt").
  // Ideally, place this file within the same project directory.
  string string_candidate_file = 22;

  // Definition of buckets for histogram aggregation.
  // Required for metrics of type INTEGER_HISTOGRAM.
  IntegerBuckets int_buckets = 8;

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

  // Specifies how the day index for an Event is determined based on the
  // when the event was 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 {
    reserved 2;
    reserved "owner";

    // The date (inclusive) after which this metric definition expires and data
    // collection may cease. If not set, the metric is considered expired.
    // Format: yyyy/mm/dd. Must be no more than one year in the future.
    string expiration_date = 1;

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

  // Report IDs that have been previously used and deleted from this metric.
  // These IDs must not be reused in new reports.
  repeated uint32 deleted_report_ids = 26;

  // Experimental. DO NOT USE!
  // A field in the STRUCT metric.
  message StructField {
    uint32 id = 1;
    string name = 2;

    enum FieldType {
      FIELD_TYPE_UNSPECIFIED = 0;

      BOOL = 1;

      ENUM = 2;

      STRING = 3;
    }

    FieldType type = 3;

    // This is a required field for fields of type enum.
    map<uint32, string> enum = 4;

    // Path to a file containing candidate strings for GROUP_BY aggregations on
    // this field (if it has type STRING). The path should be relative to the
    // Cobalt registry root (e.g., "$CUSTOMER/$PROJECT/candidate_strings.txt").
    // If set here, it overrides the need to set it in report aggregates.
    string string_candidate_file = 5;
  }

  // Experimental. DO NOT USE!
  // A list of fields in the STRUCT metric.
  repeated StructField struct_fields = 27;
}

// Defines standard units for INTEGER and INTEGER_HISTOGRAM metrics.
enum MetricUnits {
  // Use `metric_units_other` field in MetricDefinition for custom units.
  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
}

// Defines standard semantic categories to classify the purpose of a metric.
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;
}