src/registry/report_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/aggregation_window.proto";
import "src/registry/annotations.proto";
import "src/registry/window_size.proto";

option go_package = "src/registry;config";

// A Report analyzes Events that were logged to Cobalt and emits an aggregated
// output that may then be queried or visualized by an analyst user of Cobalt.
//
// A Report is associated with a Metric and this means that the Report analyzes
// the Events that were logged to that Metric. The first step occurs on a
// Fuchsia device where Cobalt analyzes the logged Events in order to form
// Observations.
//
// An Observation is built for a particular Report. The type of observation,
// including which of several privacy-oriented Encodings is used or not, depends
// on the Report type.
//
// The Observations are sent to the Cobalt Shuffler which shuffles them in order
// to break linkability between Observations and linkability with the
// originating device. Next the shuffled Observations are sent to the Analyzer
// which aggregates Observations from all Fuchsia devices in order to generate
// a report.
//
// There are multiple types of Metrics and multiple types of Reports. Each
// Report type is compatible with only some of the Metric types.
//
// A ReportDefinition defines a Cobalt Report to be generated.
// An instance of ReportDefinition is always associated with an instance of
// MetricDefinition called the owning MetricDefinition.
// Next ID: 26
message ReportDefinition {
  reserved 5, 6, 7, 12;
  reserved "expected_population_size", "expected_string_set_size", "output_location", "threshold";

  // Unique name for this Report within its owning MetricDefinition.
  // The name must obey the syntax of a C variable name and must have length
  // at most 64. The integer |id| field is the stable identifier for a report
  // so this name may be changed. However doing this may affect the
  // names and locations of some artifacts produced by Cobalt's report
  // generation pipeline.
  string report_name = 1;

  // The unique integer ID for this report within its owning metric.
  // The user must manually set this |id| field. This is the stable identifier
  // for a report and should not be changed once data collection begins.
  uint32 id = 2;

  // A Report has one of the following types.
  // Next standard report type ID: 21
  enum ReportType {
    reserved 5, 6, 7, 19;
    reserved "HIGH_FREQUENCY_STRING_COUNTS", "NUMERIC_PERF_RAW_DUMP",
        "STRING_COUNTS_WITH_THRESHOLD", "STRING_HISTOGRAMS";

    REPORT_TYPE_UNSET = 0;

    // Gives the total, daily, fleet-wide count of the number of occurrences of
    // each of a set of event types. Supports the use of local differential
    // privacy.
    //
    // Supported Input Types:
    //   - Metric type: EVENT_OCCURRED
    //     Encoding: Basic RAPPOR
    //     Observation type: BasicRapporObservation
    //
    // ReportDefinition fields particular to this type:
    //   - local_privacy_noise_level # Gives Basic RAPPOR parameters
    //
    // Report row type: SimpleOccurrenceCountReportRow. (See report_row.proto)
    //
    // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
    SIMPLE_OCCURRENCE_COUNT = 1;

    // Gives the total, daily, fleet-wide count of the number of occurrences of
    // each of a set of event types, for each of a set of components.
    //
    // Supported Input Types:
    //   - Metric type: EVENT_COUNT
    //     Encoding: component name is hashed
    //     Observation type: IntegerEventObservation
    //     Observation value field: count
    //
    // ReportDefinition fields particular to this type:
    //   - candidate_list # All known component names
    //   - candidate_file # File with all known component names
    //
    // Report row type: EventComponentOccurrenceCountReportRow.
    // (See report_row.proto)
    //
    // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
    EVENT_COMPONENT_OCCURRENCE_COUNT = 2;

    // Gives daily, fleet-wide aggregate statistics of a numerical metric of one
    // or more event types, associated with one or more components
    //
    // Supported Input Types:
    //   - Metric types: ELAPSED_TIME, EVENT_COUNT, FRAME_RATE, MEMORY_USAGE
    //     Encoding: component name is hashed
    //     Observation type: IntegerEventObservation
    //     Observation value field: Respectively, duration_microseconds
    //                              occurrences, round(fps * 100), bytes
    //
    // ReportDefinition fields particular to this type:
    //   - candidate_list # All known component names
    //   - candidate_file # File with all known component names
    //   - percentiles # A list of percentiles between 0-100 to include in the
    //         report
    //
    // Report row type: NumericAggregationReportRow.
    // (See report_row.proto)
    //
    // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
    NUMERIC_AGGREGATION = 3;

    // Gives daily, fleet-wide histograms of an integer-valued metric of one or
    // more event types, associated with one or more components
    //
    // Supported Input Types:
    //   - Metric types: ELAPSED_TIME, EVENT_COUNT, FRAME_RATE, MEMORY_USAGE
    //     Encoding, Observation type, Observation value field: Same as
    //         NUMERIC_AGGREGATION above.
    //   - Metric type: INT_HISTOGRAM
    //     Encoding: Component name is hashed, values are bucketed
    //     Observation type: HistogramObservation
    //
    // ReportDefinition fields particular to this type:
    //   - candidate_list # All known component names
    //   - candidate_file # File with all known component names
    //   - int_buckets # Definition of integer-range buckets for histogram
    //                 # Not used for Metric type INT_HISTOGRAM because the
    //                 # Metric already contains this field.
    //
    // Report row type: IntRangeHistogramReportRow
    // (See report_row.proto)
    //
    // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
    INT_RANGE_HISTOGRAM = 4;

    ////////////////////// Locally aggregated ReportTypes //////////////////////
    //
    // Report types for which logged Events are aggregated on each device over a
    // specified number of days. Each day, each device sends an Observation of
    // the aggregate of the Events over the rolling window ending on that day.
    //
    ////////////////////////////////////////////////////////////////////////////

    // For each of a set of events, gives an estimate of the number of unique
    // devices on which that event occurred at least once during a rolling
    // window. Supports the use of local differential privacy with Basic RAPPOR.
    //
    // Each device sends an observation each day for each window size registered
    // in a ReportDefinition of this type, whether or not any of the associated
    // events occurred in the window ending on that day.
    //
    // Supported Input Types:
    //   - Metric type: EVENT_OCCURRED
    //   - Encoding: Basic RAPPOR. In the decoding step one should not assume
    //               that the true bit vector has exactly 1 bit set, but rather
    //               can have any number of bits set. This encoding/decoding
    //               scheme is the same as the Instantanous Randomized Response
    //               in the RAPPOR paper (https://arxiv.org/pdf/1407.6981.pdf).
    //   - Observation type: UniqueActivesObservation
    //
    // ReportDefinition fields particular to this type:
    //   - local_privacy_noise_level # Gives Basic RAPPOR parameters.
    //   - window_size # A list of window sizes in days.
    //
    // Report row type: UniqueActivesReportRow.
    // (see report_row.proto)
    //
    // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
    UNIQUE_N_DAY_ACTIVES = 8;

    // For each of a set of events, for each of a set of component labels, for
    // a rolling window of a particular number of days, gives summary statistics
    // of the number of occurrences on individual devices of that event, with
    // that component, during the window.
    //
    // Supported Input Types:
    //    - Metric type: EVENT_COUNT, ELAPSED_TIME, FRAME_RATE, MEMORY_USAGE
    //    - Encoding: component name is hashed
    //    - Observation type: PerDeviceNumericObservation
    //
    // ReportDefinition fields particular to this type:
    //    - candidate_list # All known component names.
    //    - candidate_file # File with all known component names.
    //    - window_size # A list of window sizes in days
    //    - aggregation_type # How numeric values should be aggregated on-device
    //
    // Report row type: PerDeviceNumericStatsReportRow.
    // (See report_row.proto)
    //
    // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
    PER_DEVICE_NUMERIC_STATS = 9;

    // For each of a set of events, for each of a set of component labels, for
    // a rolling window of a particular number of days, gives summary statistics
    // of the number of occurrences on individual devices of that event, with
    // that component, during the window.
    //
    // Supported Input Types:
    //    - Metric type: EVENT_COUNT, ELAPSED_TIME, FRAME_RATE, MEMORY_USAGE
    //    - Encoding: component name is hashed
    //    - Observation type: PerDeviceHistogramObservation
    //
    // ReportDefinition fields particular to this type:
    //    - candidate_list # All known component names.
    //    - candidate_file # File with all known component names.
    //    - aggregation_window # A list of desired aggregation windows in days
    //                           or hours.
    //    - aggregation_type # How numeric values should be aggregated on-device
    //    - int_buckets # Definition of integer-range buckets for histogram
    //
    // Report row type: PerDeviceNumericStatsReportRow.
    // (See report_row.proto)
    //
    // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
    PER_DEVICE_HISTOGRAM = 10;

    ///////////////////////////////////////////////////////////////////////////
    //
    // Cobalt 1.1 report types are below this line.
    //
    ////////////////////////////////////////////////////////////////////////////

    // For each system_profile SP and each event_vector EV, produces the total
    // count of all occurrences on all devices in the fleet with system profile
    // SP of the event associated with EV over the course of the report day.
    // For example, a report of this type might give the total number of times
    // a medium, red widget was used across the fleet yesterday.
    //
    // Input metric types: OCCURRENCE
    //
    // Local aggregation: COUNT
    // Local aggregation period: 1 hour
    // Global aggregation: OCCURRENCE_COUNTS
    //
    // Output report row type: OccurrenceCountReportRow
    // (See report_row.proto)
    //
    // ReportDefinition fields particular to this type:
    //    none
    //
    // This report type is part of Cobalt 1.1. Do not use it yet.
    FLEETWIDE_OCCURRENCE_COUNTS = 11;

    // For each system_profile SP and each event_vector EV, produces the count
    // of the number of unique devices with system profile SP for which EV
    // “is accepted” during the aggregation period, which must
    // be DAYS_1, DAYS_7 or DAYS_30.
    //
    // There are different versions of what “is accepted” means depending on
    // which local aggregation procedure is specified:
    //
    // AT_LEAST_ONCE. In this case EV is accepted if EV was logged at least once
    // during the aggregation period. For example, a report of this type might
    // give the total number of devices with system profile SP on which a
    // medium, red widget was used at least once in the seven-day period
    // ending yesterday.
    //
    // SELECT_FIRST, SELECT_MOST_COMMON. In this case EV is accepted if the
    // category selection procedure selected EV. For example, a report of this
    // type using SELECT_MOST_COMMON might give the total number of devices
    // with system profile SP on which most of the widgets used during the
    // seven-day period ending yesterday were medium-red.
    //
    // Input metric types: OCCURRENCE
    //
    // Local aggregation: AT_LEAST_ONCE, SELECT_FIRST, or SELECT_MOST_COMMON
    // Local aggregation period: DAYS_1, DAYS_7 or DAYS_30.
    // Global aggregation: OCCURRENCE_COUNTS
    //
    // Output report row type: OccurrenceCountReportRow
    // (See report_row.proto)
    //
    // ReportDefinition fields particular to this type:
    //   - local_aggregation_procedure
    //   - local_aggregation_period
    //
    // This report type is part of Cobalt 1.1. Do not use it yet.
    UNIQUE_DEVICE_COUNTS = 12;

    // For each system_profile SP and each event_vector EV, produces an
    // int-range histogram such that in each int range bucket it gives the
    // number of unique devices with system_profile SP for which an integer
    // value, aggregated locally on device over the aggregation period,
    // associated with EV, falls into the bucket.
    //
    // There are two versions of this depending on the metric type:
    //
    // With metrics of type OCCURRENCE the integer values are occurrence counts.
    // For example, for the integer bucket 10-100, a report of this type might
    // give the number of devices with system profile SP on which a medium,
    // red widget was used between 10 and 100 times in the seven-day period
    // ending yesterday.
    //
    // With metrics of type INTEGER the integer values are computed statistics.
    // For example, for the integer bucket 10-100, a report of this type that
    // specifies the MINIMUM local aggregation procedure might give the number
    // of devices with system profile SP on which the minimum temperature of a
    // medium red widget over the seven-day period ending yesterday was between
    // 10 and 100 degrees.
    //
    // Input metric types: OCCURRENCE or INTEGER
    //
    // Local aggregation: COUNT_AS_INTEGER (used with OCCURRENCE metrics) or
    //                    NUMERIC_STAT (used with INTEGER metrics)
    // Local aggregation period: DAYS_1, DAYS_7 or DAYS_30.
    // Global aggregation: INTEGER_HISTOGRAMS
    //
    // Output report row type: IntegerHistogramReportRow
    // (See report_row.proto)
    //
    // ReportDefinition fields particular to this type:
    //   - local_aggregation_procedure (only when the metric type is INTEGER)
    //   - local_aggregation_period
    //   - int_buckets (this is used only on the server for reports without
    //     added privacy, but is used on the client for reports with added
    //     privacy)
    //
    // This report type is part of Cobalt 1.1. Do not use it yet.
    UNIQUE_DEVICE_HISTOGRAMS = 13;

    // For each system_profile SP and each event_vector EV, produces an
    // int-range histogram such that in each int range bucket it gives the
    // number of values, associated with EV, from devices
    // with system_profile SP, that fall into the bucket, where each device
    // computes one such value per hour.
    //
    // Computationally this report type is identical to
    // UNQIQUE_DEVICE_HISTOGRAMS except that the local aggregation period
    // used is one hour and so the counts in each buckets are not interpreted
    // as a number of unique devices.
    //
    // There are two versions of this depending on the metric type:
    //
    // With metrics of type OCCURRENCE the integer values are occurrence counts.
    // For example, for the integer bucket 10-100, a report of this type might
    // give the number of times that the hourly count of medium red widgets
    // used was between 10 and 100 over devices with system profile SP,
    // yesterday.
    //
    // With metrics of type INTEGER the integer values are computed statistics.
    // For example, for the integer bucket 10-100, a report of this that
    // specifies the MINIMUM local aggregation procedure might give the number
    // of times that the minimum temperature over an hour of all medium red
    // widgets used was between 10 and 100 degrees over all devices with
    // system profile SP, yesterday.
    //
    // Input metric types: OCCURRENCE or INTEGER
    //
    // Local aggregation: COUNT_AS_INTEGER (used with OCCURRENCE metrics) or
    //                    NUMERIC_STAT (used with INTEGER metrics)
    // Local aggregation period: one hour
    // Global aggregation: INTEGER_HISTOGRAMS
    //
    // Output report row type: IntegerHistogramReportRow
    // (See report_row.proto)
    //
    // ReportDefinition fields particular to this type:
    //   - local_aggregation_procedure (only when the metric type is INTEGER)
    //   - int_buckets (this is used only on the server for reports without
    //     added privacy, but is used on the client for reports with added
    //     privacy)
    //
    // This report type is part of Cobalt 1.1. Do not use it yet.
    HOURLY_VALUE_HISTOGRAMS = 14;

    // For each system_profile SP and each event_vector EV, produces an
    // int-range histogram such that in each int range bucket it gives the
    // number of integer measurements, associated with EV, logged on devices
    // with system_profile SP, that fall into the bucket. Here we are counting
    // each value logged by the instrumented code individually and so the rate
    // at which values are being recorded is arbitrary and varies from device
    // to device. For example, for the integer bucket 10-100, a report of this
    // type might give the number of times that a medium red widget's
    // temperature was measured as being between 10 and 100 degrees over all
    // devices with system profile SP, yesterday. The rate at which these
    // widget temperature measurements are taken is arbitrary and may vary
    // from device to device.
    //
    // Input metric types: INTEGER or INTEGER_HISTOGRAM
    //
    // Local aggregation: INTEGER_HISTOGRAM
    // Local aggregation period: one hour
    // Global aggregation: INTEGER_HISTOGRAMS
    //
    // Output report row type: IntegerHistogramReportRow
    // (See report_row.proto)
    //
    // ReportDefinition fields particular to this type:
    //   - int_buckets (Only with metric_type = INTEGER)
    //
    // This report type is part of Cobalt 1.1. Do not use it yet.
    FLEETWIDE_HISTOGRAMS = 15;

    // For each system_profile SP and each event_vector EV, produces the sum
    // and count of many integer measurements associated with EV, logged on
    // devices with system_profile SP. Here we are counting each value logged
    // by the instrumented code individually and so the rate at which values are
    // being recorded is arbitrary and varies from device to device. This allows
    // us to  produce a fleetwide mean. For example, a report of this type might
    // give the mean of all temperature measurements of medium-red widgets
    // yesterday, across all devices with system profile SP, regardless of how
    // many temperature measurements were taken on each device individually.
    //
    // Input metric types: INTEGER
    //
    // Local aggregation: SUM_AND_COUNT
    // Local aggregation period: one hour
    // Global aggregation: SUM_AND_COUNTS
    //
    // Output report row type: SumAndCountReportRow
    // (See report_row.proto)
    //
    // ReportDefinition fields particular to this type:
    //   none
    //
    // This report type is part of Cobalt 1.1. Do not use it yet.
    FLEETWIDE_MEANS = 16;

    // For each system_profile SP and each event_vector EV, produces several
    // numeric statistics (e.g. 95%-ile) over a set of integers associated
    // with EV, collected from all devices with system_profile SP. Each unique
    // device contributes a single value and so the distribution of the values
    // may be thought of as a distribution of unique devices.
    //
    // There are different versions of this depending on the metric type:
    //
    // With metrics of type OCCURRENCE the integer values are occurrence counts
    // over the course of the aggregation period. For example a report of this
    // type might give the 95%-ile of the counts of medium-red widgets used by
    // each device over the 7-day period ending yesterday.
    //
    // With metrics of type INTEGER the integer values are computed statistics.
    // For example, a report of this type that specifies the MINIMUM local
    // aggregation procedure might give the 95%-ile of the minimum temperature
    // over the 7-day period ending yesterday of all medium-red widgets over
    // all devices with system profile SP.
    //
    // Input metric types: OCCURRENCE or INTEGER
    //
    // Local aggregation: COUNT_AS_INTEGER (used with OCCURRENCE metrics) or
    //                    NUMERIC_STAT (used with INTEGER metrics)
    // Local aggregation period: DAYS_1, DAYS_7 or DAYS_30.
    // Global aggregation: NUMERIC_STATS
    //
    // Output report row type: NumericStatsReportRow
    // (See report_row.proto)
    //
    // ReportDefinition fields particular to this type:
    //   - local_aggregation_procedure (only when the metric type is INTEGER)
    //   - local_aggregation_period
    //
    // This report type is part of Cobalt 1.1. Do not use it yet.
    UNIQUE_DEVICE_NUMERIC_STATS = 17;

    // For each system_profile SP and each event_vector EV, produces several
    // numeric statistics (e.g. 95%-ile) over a set of integers associated
    // with EV, collected from all devices with system_profile SP. Each unique
    // device contributes a value every hour and so the distribution of the
    // values may NOT be thought of as a distribution of unique devices.
    //
    // Computationally this report type is identical to
    // UNIQUE_DEVICE_NUMERIC_STATS except that the local aggregation period
    // used is one hour.
    //
    // There are different versions of this depending on the metric type:
    //
    // With metrics of type OCCURRENCE the integer values are occurrence counts
    // over the course of the hour. For example a report of this
    // type might give the 95%-ile of the counts of medium-red widgets used in
    // any one hour period on any device with System profile SP, yesterday.
    //
    // With metrics of type INTEGER the integer values are computed statistics.
    // For example, a report of this type that specifies the MINIMUM local
    // aggregation procedure might give the 95%-ile of the minimum temperature
    // over any one-hour period of medium-red widgets use on any device
    // with system profile SP, yesterday.
    //
    // Input metric types: OCCURRENCE or INTEGER
    //
    // Local aggregation: COUNT_AS_INTEGER (used with OCCURRENCE metrics) or
    //                    NUMERIC_STAT (used with INTEGER metrics)
    // Local aggregation period: 1 hour
    // Global aggregation: NUMERIC_STATS
    //
    // Output report row type: NumericStatsReportRow
    // (See report_row.proto)
    //
    // ReportDefinition fields particular to this type:
    //   - local_aggregation_procedure (only when the metric type is INTEGER)
    //
    // This report type is part of Cobalt 1.1. Do not use it yet.
    HOURLY_VALUE_NUMERIC_STATS = 18;

    // For each system_profile SP and each event_vector EV, produces the total
    // count of all occurrences of a string value on all devices in the fleet
    // with system profile SP of the event associated with EV over the course
    // of the report day.
    //
    // Input metric types: STRING
    //
    // Local aggregation: STRING_HISTOGRAM
    // Local aggregation period: 1 hour
    // Global aggregation: STRING_HISTOGRAMS
    //
    // Output report row type: StringCountReportRow
    // (See report_row.proto)
    //
    // ReportDefinition fields particular to this type:
    //    candidate_file
    //
    // This report type is part of Cobalt 1.1. Do not use it yet.
    STRING_COUNTS = 20;

    /////////////////////// Custom Raw Dump Report /////////////////////////////

    // Gives a raw dump of the Observations for a CustomMetric for a day.
    //
    // Supported Input Types:
    //   - Metric types: CUSTOM
    //     Encoding: none
    //     Observation type: CustomObservation
    //
    // ReportDefinition fields particular to this type: none
    //
    // Report fields:
    //   - date
    //   - system_profile # One or more fields from the SystemProfile message
    //                      type (cobalt/observation.proto) describing the
    //                      system on which the events occurred.
    //   - event
    //   - component
    //   - part-1, part-2, ... # The values of the custom parts
    //
    // Example report:
    //
    // Date, SystemProfile, Component, Event,  part-1, part-2, part-3, ...
    // -------------------------------------------------------------------------
    // 2018-7-25,<sys-prof 1>,"Part 1","value1"
    // 2018-7-25,<sys-prof 2>,"Part 1","value1"
    // 2018-7-25,<sys-prof 1>,"Part 2","value2"
    //
    // A report of this type must be associated with a MetricDefinition of type
    // CustomMetric. Observations for the Report will be of type
    // CustomObservation
    CUSTOM_RAW_DUMP = 9999;
  }
  ReportType report_type = 3;

  ////////////////  Fields specific to some report types /////////////////

  // A level of random noise to use when encoding observations for local
  // differential privacy.
  enum LocalPrivacyNoiseLevel {
    // local_privacy_noise_level must be explicitly set when using
    // Basic RAPPOR.
    NOISE_LEVEL_UNSET = 0;

    // p = 0.0, q = 1.0
    NONE = 1;

    // p = 0.01, q = 0.99
    SMALL = 2;

    // p = 0.1, q = 0.9
    MEDIUM = 3;

    // p = 0.25, q = 0.75
    LARGE = 4;
  }

  // This field is used with all report types that use local differential
  // privacy in Cobalt 1.0:
  //
  // SIMPLE_OCCURRENCE_COUNT
  // UNIQUE_N_DAY_ACTIVES.
  LocalPrivacyNoiseLevel local_privacy_noise_level = 4;

  // The level of differential privacy applied to the report. Each level
  // corresponds to an epsilon value in the shuffled model. The mapping
  // from enum values to epsilon values is read from the file
  // //src/algorithms/privacy/data/epsilons.
  enum PrivacyLevel {
    PRIVACY_LEVEL_UNKNOWN = 0;

    // epsilon = infinity
    NO_ADDED_PRIVACY = 1;

    LOW_PRIVACY = 2;

    MEDIUM_PRIVACY = 3;

    HIGH_PRIVACY = 4;
  }

  // This field is used to specify the privacy level for a Cobalt 1.1 report.
  // All Cobalt 1.1 report types other than CUSTOM_RAW_DUMP support differential
  // privacy.
  PrivacyLevel privacy_level = 20;

  // The probability of a bit being flipped when performing RAPPOR encoding for
  // Cobalt 1.1 reports.
  //
  // The value of this field is computed by the registry parser as a function of
  // other privacy-related fields and an estimate of the user population size.
  // It should not be set manually in the Cobalt registry.
  double prob_bit_flip = 21;

  // When reporting numerical values with privacy, the values are mapped to
  // indices from 0 to num_index_points-1 with a randomized rounding method.
  //
  // The value of this field is computed by the registry parser as a function of
  // other privacy-related fields and an estimate of the user population size.
  // It should not be set manually in the Cobalt registry.
  uint32 num_index_points = 22;

  // These fields specify the range of values that can be reported by a device
  // in the specified local_aggregation_period. If the true value to be reported
  // falls outside specified range, the value is clipped.
  //
  // For UNIQUE_DEVICE_NUMERIC_STATS and HOURLY_VALUE_NUMERIC_STATS, the range
  // applies to the numerical value computed for the device.
  //
  // For UNIQUE_DEVICE_HISTOGRAMS, HOURLY_VALUE_HISTOGRAMS and
  // FLEETWIDE_HISTOGRAMS, the range applies to the values contained in the
  // individual buckets for each histogram.
  //
  // For FLEETWIDE_MEANS, the range applies to the per-device sum of the value
  // to be averaged.
  //
  // If a privacy_level is specified, this field is required for reports of type
  // * UNIQUE_DEVICE_NUMERIC_STATS
  // * HOURLY_VALUE_NUMERIC_STATS
  // * UNIQUE_DEVICE_HISTOGRAMS
  // * HOURLY_VALUE_HISTOGRAMS
  // * FLEETWIDE_HISTOGRAMS
  // * FLEETWIDE_MEANS
  int64 min_value = 23;
  int64 max_value = 24;

  // This field specifies the maximum count to be reported by a device in the
  // specified local_aggregation_period. If the true count is greater than
  // max_count, then the count will be reported as max_count.
  //
  // If a privacy_level is specified, this field is required for reports of
  // type
  // * FLEETWIDE_OCCURRENCE_COUNTS
  // * FLEETWIDE_MEANS
  // * STRING_COUNTS
  uint64 max_count = 25;

  // Explicit list of known string values. Either this or |candidate_file|
  // should be used, not both. Used for the hashed |component_name|
  // field for several Report types.
  //
  // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
  repeated string candidate_list = 8 [(cobalt_options).hide_on_client = true];

  // Simple name or full path to file containing known string values.
  //
  // In Cobalt 1.0 this field is used for |component_names|. Either this or
  // |candidate_list| should be used, not both.
  //
  // In Cobalt 1.1 this field is used only for reports of type STRING.
  string candidate_file = 9;

  // A specification of integer-range buckets for a histogram.
  //
  // In Cobalt 1.0:
  // This field is used only with the INT_RANGE_HISTOGRAM Report type, but
  // not used when the Metric type is INT_HISTOGRAM because in that case the
  // MetricDefinition already contains an instance of IntegerBuckets.
  //
  // In Cobalt 1.1:
  // This field is for reports of type UNIQUE_DEVICE_HISTOGRAMS,
  // HOURLY_VALUE_HISTOGRAMS, and FLEETWIDE_HISTOGRAMS--but for
  // FLEETWIDE_HISTOGRAMS only with metrics of type INTEGER, not with metrics of
  // type INTEGER_HISTOGRAM, because in that case the MetricDefinition already
  // contains an instance of IntegerBuckets.
  IntegerBuckets int_buckets = 10;

  // This field is required for the UNIQUE_N_DAY_ACTIVES and
  // PER_DEVICE_NUMERIC_STATS Report types. It is not used with any other
  // report types.
  //
  // Used to specify the length in days of the rolling window for that
  // report type. Cobalt will send a separate Observation for each
  // WindowSize specified.
  //
  // TODO(pesk): make this a reserved name and ID once support for
  // |aggregation_window| is done and existing reports are updated.
  //
  // This field will be deleted in Cobalt 1.1 and replaced with
  // |local_aggregation_period|.
  // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
  repeated WindowSize window_size = 11;

  // A time window in units of days or hours over which to aggregate events
  // on-device. Cobalt will send a separate Observation for each
  // OnDeviceAggregationWindow specified.
  //
  // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
  repeated OnDeviceAggregationWindow aggregation_window = 16;

  // This field can be used with all Report types. When set, the generated
  // report will exclude an Observation if there are not at least
  // |reporting_threshold| number of distinct devices reporting Observations
  // with the same ObservationMetadata.
  uint32 reporting_threshold = 13;

  // How to aggregate numeric values on a device.
  //
  // This enum will be deleted in Cobalt 1.1 and replaced with
  // the LocalAggregationProcedure enum.
  // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
  enum OnDeviceAggregationType {
    // Sum the values.
    SUM = 0;

    // Take the minimum value.
    MIN = 1;

    // Take the maximum value.
    MAX = 2;
  }

  // This field is required for the PER_DEVICE_NUMERIC_STATS report type.
  // It is not used with any other report type.
  //
  // Used to specify how numeric values should be aggregated on-device.
  // If SUM is chosen, each device will generate an Observation containing
  // the sum of logged numeric values over a specified aggregation window.
  // If MIN (resp., MAX) is chosen, an Observation for this report will
  // contain the minimum (resp., maximum) numeric value logged during the
  // aggregation window.
  //
  // This field will be deleted in Cobalt 1.1 and replaced with the
  // field |local_aggregation_procedure|.
  // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
  OnDeviceAggregationType aggregation_type = 14;

  // This field is optional for the NUMERIC_AGGREGATION report type.  It is not
  // used with any other report type.
  //
  // Used to specify which additional percentiles to include in the report
  // output.  Each value should be between 0 and 100.
  //
  // TODO(fxb/45463) Delete when all users move to Cobalt 1.1.
  repeated uint32 percentiles = 15;

  // Local (on-device) aggregation procedures.
  //
  // This enum is part of Cobalt 1.1. Do not use it yet
  enum LocalAggregationProcedure {
    LOCAL_AGGREGATION_PROCEDURE_UNSET = 0;

    // Numerical statistic aggregation procedures to be used with reports
    // of type UNIQUE_DEVICE_HISTOGRAMS, HOURLY_VALUE_HISTOGRAMS,
    // UNIQUE_DEVICE_NUMERIC_STATS and HOURLY_VALUE_NUMERIC_STATS.
    // TODO(zmbush): Rename these to remove the '_PROCEDURE' suffix once the
    //               'OnDeviceAggregationType' enum is removed.
    SUM_PROCEDURE = 1;
    MIN_PROCEDURE = 2;
    MAX_PROCEDURE = 3;
    MEAN = 4;
    MEDIAN = 5;
    // The value of N is set in the field
    //    |local_aggregation_procedure_percentile_n|.
    PERCENTILE_N = 6;

    // Logical aggregation procedures to be used with reports of type
    // UNIQUE_DEVICE_COUNTS
    AT_LEAST_ONCE = 7;
    SELECT_FIRST = 8;
    SELECT_MOST_COMMON = 9;
  }

  // This field is part of Cobalt 1.1. Do not use it yet.
  //
  // In Cobalt 1.1 this field is required for reports of type
  // UNIQUE_DEVICE_HISTOGRAMS, HOURLY_VALUE_HISTOGRAMS,
  // UNIQUE_DEVICE_NUMERIC_STATS, HOURLY_VALUE_NUMERIC_STATS
  // and UNIQUE_DEVICE_COUNTS. Different report types support
  // different values of this field. See the comments on the
  // enum values in LocalAggregationProcedure.
  LocalAggregationProcedure local_aggregation_procedure = 17;

  // This field is required when
  // local_aggregation_procedure = LOCAL_AGGREGATION_PROCEDURE_PERCENTILE_N.
  // In this case it gives the value of N to use. Otherwise this field is
  // ignored.
  //
  // This field is part of Cobalt 1.1. Do not use it yet.
  uint32 local_aggregation_procedure_percentile_n = 18;

  // The local aggregation period is specified in the UNIQUE_DEVICE_*
  // report types.
  //
  // This field is part of Cobalt 1.1. Do not use it yet.
  WindowSize local_aggregation_period = 19;

  ///////////////////  Fields used by all report types ///////////////////
  // Next id: 103

  // The list of SystemProfileFields to include in each row of the report.
  // Optional.
  repeated SystemProfileField system_profile_field = 100;

  // Configuration of differentially private release for this report.
  DifferentialPrivacyConfig dp_release_config = 101;

  // Overrides the location to where Cobalt exports this Report.
  // This field is implementation-specific. If omitted Cobalt will use its
  // default settings to determine the location of the exported report.
  string export_location_override = 102;

  // If the system profile value changed during the aggregation window specified for this report,
  // system_profile_selection specifies which system profile to report for each device.
  SystemProfileSelectionPolicy system_profile_selection = 103;
}

// A specification for SystemProfile selection policy.
enum SystemProfileSelectionPolicy {
  // The default implementation. May change without notice.
  SELECT_DEFAULT = 0;

  // Always report the last SystemProfile seen in the aggregation_window.
  SELECT_LAST = 1;

  // Always report the first SystemProfile seen in the aggregation_window.
  SELECT_FIRST = 2;
}

message DifferentialPrivacyConfig {
  float epsilon = 1;
  float delta = 2;
}

// A specification of a field from SystemProfile. These are used in a ReportDefinition to specify
// which fields should be included in the generated Observations and reports.
enum SystemProfileField {
  OS = 0;
  ARCH = 1;
  BOARD_NAME = 2;
  PRODUCT_NAME = 3;
  SYSTEM_VERSION = 4;
  CHANNEL = 5;
  REALM = 6;
}

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