// Copyright 2016 The Fuchsia Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto3";

package cobalt;

option go_package = "config";

// A specification of a field from SystemProfile. These are used in a Metric to
// specify which fields should be included in collected Observations and they
// are used in a ReportConfig to specify which fields should be included in each
// row of a generated report.
enum SystemProfileField {
  OS = 0;
  ARCH = 1;
  BOARD_NAME = 2;
  PRODUCT_NAME = 3;
  SYSTEM_VERSION = 4;
  CHANNEL = 5;
}

// ExponentialIntegerBuckets is used to define a partition of the integers into
// a finite number of exponentially increasing buckets.
//
// Let n = num_buckets. Then there are n+2 buckets indexed 0,...,n+1.
//
// The bucket boundaries are:
// a[0] = floor
// a[1] = floor + initial_step
// a[2] = floor + initial_step * step_multiplier
// a[3] = floor + initial_step * step_multiplier ^ 2
// a[4] = floor + initial_step * step_multiplier ^ 3
// and in general, for i = 1, 2, 3 ... n
// a[i] = floor + initial_step * step_multiplier ^ (i-1)
//
// Then, the buckets are defined as follows:
// Bucket 0 is the underflow bucket: (-infinity, floor)
// Bucket i for 0 < i < n+1: [a[i-1], a[i])
// Bucket n+1 is the overflow bucket: [a[n], +infinity)
//
// Examples:
// floor = 0
// num_buckets = 3
// initial_step = 10
// step_multiplier = 10
// Then, the buckets are:
// (-infinity, 0), [0, 10), [10, 100), [100, 1000), [1000, +infinity)
//
// floor = 0
// num_buckets = 3
// initial_step = 2
// step_multiplier = 2
// Then, the buckets are:
// (-infinity, 0), [0, 2), [2, 4), [4, 8), [8, +infinity)
//
// floor = 10
// num_buckets = 3
// initial_step = 2
// step_multiplier = 2
// Then, the buckets are:
// (-infinity, 10), [10, 12), [12, 14), [14, 18), [18, +infinity)
//
// floor = 0
// num_buckets = 3
// initial_step = 100
// step_multiplier = 10
// Then, the buckets are:
// (-infinity, 0), [0, 100), [100, 1000), [1000, 10000), [10000, +infinity)
//
message ExponentialIntegerBuckets {
  int64 floor = 1;

  // num_buckets must be at least 1.
  uint32 num_buckets = 2;

  // Must be at least one.
  uint32 initial_step = 3;

  // Must be at least one.
  uint32 step_multiplier = 4;
};

// LinearIntegerBuckets is used to define a partition of the integers into a
// finite number of buckets of equal size.
//
// Let n = num_buckets. Then there are n+2 buckets indexed 0,...,n+1.
// Bucket 0 is the underflow bucket: (-infinity, floor)
// Bucket n+1 is the overflow bucket: [lower + step_size * n, +infinity)
//
// For i = 1 to n, the bucket i is defined as
// [floor + step_size * (i-1), floor + step_size * i)
//
// Example: floor = 0, num_buckets = 3, step_size = 10.
// (-infinity, 0), [0, 10), [10, 20), [20, 30), [30, +inifinity)
message LinearIntegerBuckets {
  int64 floor = 1;

  // Must be at least one.
  uint32 num_buckets = 2;

  // Must be at least one.
  uint32 step_size = 3;
}

message IntegerBuckets {
  oneof buckets {
    ExponentialIntegerBuckets exponential = 1;
    LinearIntegerBuckets linear = 2;
  }
};

// A |Metric| is composed of one or more |MetricParts|. A |MetricPart| has a
// name which is specified as the key in the |parts| field of |Metric|, a
// description and a data type which specifies the type of a |ValuePart| that
// should be encoded for this MetricPart.
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;
}

// A Metric represents a real-world value to be observed and reported by Cobalt.
// For example "Fuchsia Usage Hour-of-the-day" might be a metric that measures
// Fuchsia system usage as a function of the hour of the day.
// Each Observation from the Encoder is for a particular metric.
// Each Observation for the metric "Fuchsia Usage Hour-of-the-day" would
// report the hour of the day for a particular usage of Fuchsia.
// A Metric has one or more named parts and each Observation sent by the Encoder
// must contain ObservationParts corresponding to these Metric parts.
// For example the Metric described above might have only one part named
// "hour" and so each Observation for this metric should have a single
// ObservationPart named "hour". On the other hand the Metric "Fuchsia Usage
// City-and-Rating" might have two parts called "City" and "Rating".
message Metric {
  // Next ID: 11

  // These three numbers form this Metric's unique ID in the Cobalt Config
  // DB.
  uint32 customer_id = 1;
  uint32 project_id = 2;
  uint32 id = 3;

  string name = 4;
  string description = 5;

  // The keys are the names of the part.
  map<string, MetricPart> parts = 6;

  // The list of SystemProfileFields to include in the metadata for each
  // observation. When sent to the Shuffler this will be sent only once per
  // ObservationBatch.
  repeated SystemProfileField system_profile_field = 8;

  // A ShufflerBackend specifies which backend an observation should be sent to.
  enum ShufflerBackend {
    // The legacy GRPC GKE backend
    LEGACY_BACKEND = 0;
    // The first version of the clearcut backend.
    V1_BACKEND = 1;
  }
  // Specifies a destination where observations should be sent.
  ShufflerBackend backend = 9;

  // A TimeZonePolicy specifies how the day_index of an Observation should
  // be computed based on the actual time of encoding.
  enum TimeZonePolicy {
    // There is no default. Either LOCAL or UTC must be specified.
    UNSET = 0;

    // Use the local date at encoding time to compute the day_index.
    LOCAL = 1;

    // Use the date in UTC at encoding time to compute the day_index.
    UTC = 2;
  }

  // Which TimeZonePolicy should Encoders use when encoding Observations for
  // this metric?
  TimeZonePolicy time_zone_policy = 7;

  message Metadata {
    // The time 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.
    //
    // Note: This should be a date encoded as yyyy/mm/dd and should not be
    // further than 1 year in the future.
    string expires_after = 1;

    // Primary contact for questions/bugs regarding this metric (may be a
    // group). This should be a fully qualified email address (e.g.
    // my-group@test.com)
    string owner = 2;

    // This represents the highest stage of build for which a metric will be
    // reported. A DEBUG metric will not be reported in FISHFOOD or above, etc.
    // A metric that should always be reported should have a value of PROD.
    // The list of metrics with this value should be kept as small as feasible.
    enum BuildLevel {
      NEVER_REPORT = 0;

      // These should all be the same as BuildLevel in observation.proto.
      DEBUG = 10;
      FISHFOOD = 20;
      DOGFOOD = 40;
      PROD = 99;
    }
    BuildLevel max_build_level = 4;
  }
  Metadata meta_data = 10;
}

// Constains the list of all Metrics that are registered in the
// Cobalt system. An instance of RegisteredMetrics is deserialized
// from a text file.
message RegisteredMetrics {
  repeated Metric element = 1;
}