src/pb/report_row.proto

syntax = "proto3";

package cobalt;

import "src/pb/common.proto";

////////////////////////////////////////////////////////////////////////////////
// NOTE: This file is used by the Cobalt server and not by the client. It is
// included in the client repo only for reference. The canonical version of this
// file is located in Google's internal code repository, and the file is
// automatically copied to Cobalt's open source Git repo.  Do
// not edit the copy of this file in the open-source Cobalt Git repo as those
// edits will be overwritten when the file is next copied.
////////////////////////////////////////////////////////////////////////////////

// A row of output for reports that use the OCCURRENCE_COUNTS global aggregation
// procedure: FLEETWIDE_OCCURRENCE_COUNTS and UNIQUE_DEVICE_COUNTS.
//
// This row gives a total count that is associated with a date, a system_profile
// and an event_vector.
//
// This is part of Cobalt 1.1.
message OccurrenceCountReportRow {
  // The report date. This is the date on which the local aggregation period
  // ended, as measured on the device. This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The event_vector labels for this row.
  // There will be one event_label for each metric dimension
  // that was included in the report, in the order the dimensions are declared
  // in the ReportDefinition. If the ReportDefinition specifies no metric
  // dimensions should be included then this repeated field will be empty.
  //
  // For each dimension, if the event_code in that dimension of the event_vector
  // has not been assigned a label, then this will be a string of the form
  // "<code 42>", where `42` is the numeric event code observed.
  repeated string event_labels = 3;

  // The sum of the `counts`s associated with this row's event_vector, from all
  // Observations included in the report from devices with the `system_profile`.
  // Unless the report is configured to not use any local differential privacy
  // noise, this value is an estimate. Also the value is truncated to
  // MAX_DOUBLE.
  double count = 4;
}

// A row of output for reports that use the INTEGER_HISTOGRAMS global
// aggregation procedure: FLEETWIDE_HISTOGRAMS, UNIQUE_DEVICE_HISTOGRAMS,
// HOURLY_VALUE_HISTOGRAMS.
//
// This row gives the count for one bucket of an int-range histogram
// associated with a date, a system_profile and an event_vector.
//
// This is part of Cobalt 1.1.
message IntegerHistogramReportRow {
  // The report date. This is the date on which the local aggregation period
  // ended, as measured on the device. This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The event_vector labels for this row.
  // There will be one event_label for each metric dimension
  // that was included in the report, in the order the dimensions are declared
  // in the ReportDefinition. If the ReportDefinition specifies no metric
  // dimensions should be included then this repeated field will be empty.
  //
  // For each dimension, if the event_code in that dimension of the event_vector
  // has not been assigned a label, then this will be a string of the form
  // "<code 42>", where `42` is the numeric event code observed.
  repeated string event_labels = 3;

  // The *inclusive* upper and lower bounds for this bucket.
  // required: bucket_min_value <= bucket_max_value. The bucket consists
  // of integers in the interval [bucket_min_value, bucket_max_value].
  int64 bucket_min_value = 4;
  int64 bucket_max_value = 5;

  // The bucket index, which is useful for sorting the data in visualizations.
  int32 bucket_index = 6;

  // The number of values that fall in this bucket. Unless the report is
  // configured to not use any local differential privacy noise, this value is
  // an estimate. Also the value is truncated to MAX_DOUBLE.
  double count = 7;
}

// A row of output for reports that use the SUM_AND_COUNTS global aggregation
// procedure, namely reports of type FLEETWIDE_MEAN. The goal of such a report
// is to compute the mean of a set of event values when each device in the fleet
// contributues a different number of event values. The fleetwide mean is
// given by sum/count. We emit sum and count separately so that a
// post-processing step (such as within a dashboard) may compute the mean over
// larger populations such as multiple days, multiple system_profiles, or
// multiple event_vectors.
//
// This row gives the sum and count associated with a date, a system_profile
// and an event_vector.
//
// This is part of Cobalt 1.1.
message SumAndCountReportRow {
  // The report date. This is the date on which the local aggregation period
  // ended, as measured on the device. This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The event_vector labels for this row.
  // There will be one event_label for each metric dimension
  // that was included in the report, in the order the dimensions are declared
  // in the ReportDefinition. If the ReportDefinition specifies no metric
  // dimensions should be included then this repeated field will be empty.
  //
  // For each dimension, if the event_code in that dimension of the event_vector
  // has not been assigned a label, then this will be a string of the form
  // "<code 42>", where `42` is the numeric event code observed.
  repeated string event_labels = 3;

  // The sum of all of the `sum` fields from all of the Observations included
  // in the report that are associated with this row's event_vector and from
  // devices with the `system_profile`.
  //
  // Unless the report is configured to not use any local differential privacy
  // noise, this value is an estimate. Also the value is truncated to
  // MAX_DOUBLE.
  double sum = 4;

  // The sum of all of the `count` fields from all of the Observations included
  // in the report that are associated with this row's event_vector and from
  // devices with the `system_profile`.
  //
  // Unless the report is configured to not use any local differential privacy
  // noise, this value is an estimate. Also the value is truncated to
  // MAX_DOUBLE.
  double count = 5;
}

// A row of output for reports that use the NUMERIC_STATS global aggregation
// procedure: HOURLY_VALUE_NUMERIC_STATS and UNIQUE_DEVICE_NUMERIC_STATS.
//
// This row gives the numeric statistics associated with a date, a
// system_profile and an event_vector.
//
// This is part of Cobalt 1.1.
message NumericStatsReportRow {
  // The report date. This is the date on which the local aggregation period
  // ended, as measured on the device. This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The event_vector labels for this row.
  // There will be one event_label for each metric dimension
  // that was included in the report, in the order the dimensions are declared
  // in the ReportDefinition. If the ReportDefinition specifies no metric
  // dimensions should be included then this repeated field will be empty.
  //
  // For each dimension, if the event_code in that dimension of the event_vector
  // has not been assigned a label, then this will be a string of the form
  // "<code 42>", where `42` is the numeric event code observed.
  repeated string event_labels = 3;

  // Each of the statistics below are computed over the set of all values
  // that are associated with the event_vector for this row
  // from all Observations that contributed to the report that are
  // from devices with the `system_profile`. Unless the report is
  // configured to not use any local differential privacy noise, each of these
  // value is an estimate and has been truncated to fit in a double.

  // The sum of all the values.
  double sum = 4;

  // The sum of the squares of the differences from the mean.
  double sum_of_squares = 5;

  // The count of the number of values.
  double count = 6;

  // The count of the number of values (already included in `count`) that are
  // zero.
  double zero_count = 7;

  // 1st percentile.
  double percentile_1 = 101;

  // 5th percentile.
  double percentile_5 = 105;

  // 10th percentile.
  double percentile_10 = 110;

  // 25th percentile.
  double percentile_25 = 125;

  // 50th percentile.
  double percentile_50 = 150;

  // 75th percentile.
  double percentile_75 = 175;

  // 90th percentile.
  double percentile_90 = 190;

  // 95th percentile.
  double percentile_95 = 195;

  // 99th percentile.
  double percentile_99 = 199;
}

// A row of output for reports that utilize the STRING_HISTOGRAMS global
// aggregation procedure, namely the STRING_COUNTS report type.
//
// This row gives one string and its associated count of occurrences for the
// string associated with a date, a system_profile and an event_vector.
//
// This is part of Cobalt 1.1.
message StringCountReportRow {
  // The report date. This is the date on which the local aggregation period
  // ended, as measured on the device. This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The event_vector labels for this row.
  // There will be one event_label for each metric dimension
  // that was included in the report, in the order the dimensions are declared
  // in the ReportDefinition. If the ReportDefinition specifies no metric
  // dimensions should be included then this repeated field will be empty.
  //
  // For each dimension, if the event_code in that dimension of the event_vector
  // has not been assigned a label, then this will be a string of the form
  // "<code 42>", where `42` is the numeric event code observed.
  repeated string event_labels = 3;

  // The string value. One of the candidate strings, or the string "<other>".
  string string_value = 4;

  // The count for this string.  Unless the report is
  // configured to not use any local differential privacy noise, each of these
  // value is an estimate and has been truncated to fit in a double. Also the
  // value is truncated to MAX_DOUBLE.
  double count = 5;
}

// A row of output for a report of type SIMPLE_OCCURRENCE_COUNT.
//
// Gives the total daily, fleet-wide count of the number of occurrences of an
// event with a particular event code, on a particular day, considering only
// devices matching a particular system profile.
//
// TODO(b/148809626) Delete when all users are switched to Cobalt 1.1.
message SimpleOccurrenceCountReportRow {
  // The date on which the logged events occurred, as measured on the device.
  // This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The label for the event code associated with the events that occurred. If
  // the event_code has not been assigned a label (in the event_codes field of
  // the MetricDefinition) then this will be a string of the form
  // "<code 42>", where `42` is the numeric event code observed.
  string event_code = 3;

  // The total count of the event occurrence on the `date`, over all reporting
  // devices with the `system_profile`. Unless `local_privacy_noise_level` in
  // the Reportdefintion is set to NONE, this value is an estimate.
  float count = 4;

  // An estimate of the standard error in the value of the `count`. This will
  // be zero if `local_privacy_noise_level` in the Reportdefintion is NONE.
  // Multiply this value by z_{alpha/2} to obtain the radius of an approximate
  // 100(1 - alpha)% confidence interval. For example an approximate 95%
  // confidence interval for the count is given by
  // (count_estimate - 1.96*std_error, count_estimate + 1.96 * std_error)
  // because 1.96 ~= z_{.025} meaning that P(Z > 1.96) ~= 0.025 where
  // Z ~ Normal(0, 1).
  float std_err = 5;
}

// A row of output for a report of type EVENT_COMPONENT_OCCURRENCE_COUNT.
//
// Gives the total daily fleet-wide count of the number of occurrences of an
// event with a particular event code, for a particular component, on a
// particular day, considering only devices matching a particular system
// profile.
//
// TODO(b/148809626) Delete when all users are switched to Cobalt 1.1.
message EventComponentOccurrenceCountReportRow {
  // The date on which the logged events occurred, as measured on the device.
  // This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The labels for the event codes associated with the events that occurred.
  // There is one label for each metric_dimension in the metric definition. If
  // an event code has not been assigned a label this will be a string of the
  // form "<code 42>", where `42` is the numeric event code observed.
  repeated string event_code = 3;

  // The component string associated with the events that occurred. This string
  // must have been pre-registered in the ReportDefinition (using the
  // `candidate_list` or `candidate_file` fields). There are also two special
  // values of `component`.
  // "<NONE>" is the component associated with logged events that
  // contained an empty component string.
  // "<OTHER>" is the component associated with logged events that contained
  // a non-empty component string that was not pre-registered.
  string component = 4;

  // The total sum of the event occurrence counts for events with the
  // `event_code` and `component`, on the `date`, over all
  // reporting devices with the `system_profile`.
  int64 sum = 5;

  // The count of Observations that contributed to the `sum`.
  int64 count = 6;
}

// A row of output for a report of type NUMERIC_AGGREGATION.
//
// Gives the total daily fleet-wide statistics of a numerical metric, for a
// particular event code, for a particular component, on a particular day,
// considering only devices matching a particular system profile.  The
// statistics include the number of observations, the mean, median, minimum,
// maximum, and sum.
//
// TODO(b/148809626) Delete when all users are switched to Cobalt 1.1.
message NumericAggregationReportRow {
  // The date on which the logged events occurred, as measured on the device.
  // This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The labels for the event codes associated with the events that occurred.
  // There is one label for each metric_dimension in the metric definition. If
  // an event code has not been assigned a label this will be a string of the
  // form "<code 42>", where `42` is the numeric event code observed.
  repeated string event_code = 3;

  // The component string associated with the events that occurred. This string
  // must have been pre-registered in the ReportDefinition (using the
  // `candidate_list` or `candidate_file` fields). There are also two special
  // values of `component`.
  // "<NONE>" is the component associated with logged events that
  // contained an empty component string.
  // "<OTHER>" is the component associated with logged events that contained
  // a non-empty component string that was not pre-registered.
  string component = 4;

  // The count of Observations that contributed to the statistics.
  int64 count = 5;

  // The mean value of the collected Observation values for events with the
  // `event_code` and `component`, on the `date`, over all reporting devices
  // with the `system_profile`.
  float mean = 6;

  // The median value of the collected Observation values for events with the
  // `event_code` and `component`, on the `date`, over all reporting devices
  // with the `system_profile`.
  int64 median = 7;

  // The minimum value of the collected Observation values for events with the
  // `event_code` and `component`, on the `date`, over all reporting devices
  // with the `system_profile`.
  int64 min = 8;

  // The maximum value of the collected Observation values for events with the
  // `event_code` and `component`, on the `date`, over all reporting devices
  // with the `system_profile`.
  int64 max = 9;

  // The total sum of the collected Observation values for events with the
  // `event_code` and `component`, on the `date`, over all reporting devices
  // with the `system_profile`.
  int64 sum = 10;

  // A mapping of percentiles of the collected Observation values for events
  // with the `event_code` and `component`, on the `date`, over all reporting
  // devices with the `system_profile`.  The key is a percentile between 0 and
  // 100, and the value is the fleet-wide observed value at that percentile.
  map<uint32, int64> percentiles = 11;
}

// A row of output for a report of type INT_RANGE_HISTOGRAM.
//
// Gives the value for one bucket of an integer range histogram, aggregated
// over the fleet, for a particular event code, a particular component, on a
// particular day, considering only devices matching a particular system
// profile.
//
// TODO(b/148809626) Delete when all users are switched to Cobalt 1.1.
message IntRangeHistogramReportRow {
  // The date on which the logged events occurred, as measured on the device.
  // This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The labels for the event codes associated with the events that occurred.
  // There is one label for each metric_dimension in the metric definition. If
  // an event code has not been assigned a label this will be a string of the
  // form "<code 42>", where `42` is the numeric event code observed.
  repeated string event_code = 3;

  // The component string associated with the events that occurred. This string
  // must have been pre-registered in the ReportDefinition (using the
  // `candidate_list` or `candidate_file` fields). There are also two special
  // values of `component`.
  // "<NONE>" is the component associated with logged events that
  // contained an empty component string.
  // "<OTHER>" is the component associated with logged events that contained
  // a non-empty component string that was not pre-registered.
  string component = 4;

  // String describing the interval of integers for this bucket, such as
  // "10-15".
  string bucket_name = 5;

  // The count for this bucket.
  int64 bucket_count = 6;

  // The bucket index, which is useful for sorting the data in visualizations.
  int32 bucket_index = 7;
}

// A row of output for a report of type UNIQUE_N_DAY_ACTIVES.
//
// Gives an estimate of the number of devices with a particular system profile
// which experienced at least one event with a particular event code, during a
// particular time window.
//
// TODO(b/148809626) Delete when all users are switched to Cobalt 1.1.
message UniqueActivesReportRow {
  // The date of the last day of the aggregation window, as measured on the
  // device. This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The labels for the event codes associated with the events that occurred.
  // There is one label for each metric_dimension in the metric definition. If
  // an event code has not been assigned a label this will be a string of the
  // form "<code 42>", where `42` is the numeric event code observed.
  repeated string event_code = 3;

  // The size in days of the aggregation window (deprecated).
  // TODO(pesk): remove this field once the transition to aggregation_window is
  // complete.
  uint32 window_size = 4;

  // A string describing the aggregation window, with units in hours or days.
  // The format is Nh (for a window of N hours) or Nd (for a window of N days).
  string aggregation_window = 8;

  // The total count of active devices over the aggregation window, over all
  // reporting devices with the `system_profile`. Unless
  // `local_privacy_noise_level` in the Reportdefintion is set to NONE, this
  // value is an estimate.
  float active_count = 5;

  // An estimate of the standard error in the value of `active_count`. This will
  // be zero if `local_privacy_noise_level` in the ReportDefinition is NONE.
  // Multiply this value by z_{alpha/2} to obtain the radius of an approximate
  // 100(1 - alpha)% confidence interval. For example an approximate 95%
  // confidence interval for the count is given by
  // (count_estimate - 1.96*std_error, count_estimate + 1.96 * std_error)
  // because 1.96 ~= z_{.025} meaning that P(Z > 1.96) ~= 0.025 where
  // Z ~ Normal(0, 1).
  float std_err = 6;

  // The total number of Observations received for the aggregation window,
  // over all reporting devices with the `system_profile`. This is equal to
  // the total number of Fuchsia devices with `system_profile` which were
  // awake at a time that locally aggregated Observations for this
  // ReportDefinition and this aggregation window were created and uploaded,
  // whether or not `event_code` occurred on the device during the window.
  int64 sample_size = 7;
}

// A row of output for a report of type PER_DEVICE_NUMERIC_STATS.
//
// Gives statistics over all devices of the sum of the numeric values associated
// with a particular kind of event, over all occurrences of that event on
// individual devices, over a particular time window.
//
// For example, if used with an EVENT_COUNT metric, reports statistics over all
// devices of the number of occurrences of an event on each device during the
// window. If used with an ELAPSED_TIME metric, reports statistics over all
// devices of the total amount of time logged on each device during the window.
//
// TODO(b/148809626) Delete when all users are switched to Cobalt 1.1.
message PerDeviceNumericStatsReportRow {
  // The date of the last day of the on-device aggregation window, as measured
  // on the device, using the time zone policy of the report's parent metric.
  // This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The labels for the event codes associated with the events that occurred.
  // There is one label for each metric_dimension in the metric definition. If
  // an event code has not been assigned a label this will be a string of the
  // form "<code 42>", where `42` is the numeric event code observed.
  repeated string event_code = 3;

  // The component string associated with the events that occurred. This string
  // must have been pre-registered in the ReportDefinition (using the
  // `candidate_list` or `candidate_file` fields). There are also two special
  // values of `component`:
  // "<NONE>" is the component associated with logged events that
  // contained an empty component string.
  // "<OTHER>" is the component associated with logged events that contained
  // a non-empty component string that was not pre-registered.
  string component = 4;

  // The size in days of the aggregation window (deprecated).
  // TODO(pesk): remove this field once the transition to aggregation_window is
  // complete.
  uint32 window_size = 5;

  // A string describing the aggregation window, with units in hours or days.
  // The format is Nh (for a window of N hours) or Nd (for a window of N days).
  string aggregation_window = 9;

  // The mean of the values contributing to this report row.
  float mean = 6;

  // The standard deviation of the values contributing to this report row.
  float stddev = 7;

  // The number of devices reporting a nonzero value for this report row.
  int64 unique_actives = 8;

  // Percentiles: the value of `percentile_N` is the smallest value k
  // contributed by a device to this report row such that at least N percent
  // of devices reported a value less than or equal to k.

  // 1st percentile.
  int64 percentile_1 = 101;

  // 5th percentile.
  int64 percentile_5 = 105;

  // 25th percentile.
  int64 percentile_25 = 125;

  // 50th percentile.
  int64 percentile_50 = 150;

  // 75th percentile.
  int64 percentile_75 = 175;

  // 95th percentile.
  int64 percentile_95 = 195;

  // 99th percentile.
  int64 percentile_99 = 199;

  // The number of unique devices that contributed to this report row. This is
  // equal to the number of ReportParticipationObservations received by
  // the ReportGenerator for this report, aggregation window size, and date.
  int64 sample_size = 200;
}

// A row of output for a report of type PER_DEVICE_HISTOGRAM.
//
// Gives the value for one bucket of an integer range histogram, aggregated
// over the fleet, for a particular event code, a particular component, on a
// particular day with a particular aggregation_window, considering only devices
// matching a particular system profile.
//
// TODO(b/148809626) Delete when all users are switched to Cobalt 1.1.
message PerDeviceHistogramReportRow {
  // The date on which the logged events occurred, as measured on the device.
  // This is a string in yyyy-mm-dd format.
  string date = 1;

  // A profile of the system from which the events were logged. This will be
  // populated with only the fields that are specified in the
  // `system_profile_field` entry in the ReportDefinition for this report.
  SystemProfile system_profile = 2;

  // The labels for the event codes associated with the events that occurred.
  // There is one label for each metric_dimension in the metric definition. If
  // an event code has not been assigned a label this will be a string of the
  // form "<code 42>", where `42` is the numeric event code observed.
  repeated string event_code = 3;

  // The component string associated with the events that occurred. This string
  // must have been pre-registered in the ReportDefinition (using the
  // `candidate_list` or `candidate_file` fields). There are also two special
  // values of `component`.
  // "<NONE>" is the component associated with logged events that
  // contained an empty component string.
  // "<OTHER>" is the component associated with logged events that contained
  // a non-empty component string that was not pre-registered.
  string component = 4;

  // String describing the interval of integers for this bucket, such as
  // "10-15".
  string bucket_name = 5;

  // The count for this bucket.
  int64 bucket_count = 6;

  // The bucket index, which is useful for sorting the data in visualizations.
  int32 bucket_index = 7;

  // A string describing the aggregation window, with units in hours or days.
  // The format is Nh (for a window of N hours) or Nd (for a window of N days).
  string aggregation_window = 8;

  // The number of unique devices that contributed to this report row. This is
  // equal to the number of ReportParticipationObservations received by
  // the ReportGenerator for this report, aggregation window size, and date with
  // the same SystemProfile.
  int64 fleet_size = 9;
}