report_row.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 "observation_batch.proto";

// 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.
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
  // "<event-code-42>".
  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.
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 "<event-code-0-42>" where 0 is the dimension index, and 42 is the
  // event code.
  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 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.
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 "<event-code-0-42>" where 0 is the dimension index, and 42 is the
  // event code.
  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;
}

// 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
// window of a particular number of days ending on a particular date.
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 "<event-code-0-42>" where 0 is the dimension index, and 42 is the
  // event code.
  repeated string event_code = 3;

  // The size in days of the aggregation window.
  uint32 window_size = 4;

  // The total count of active devices for the window of size |window_size|
  // ending on |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 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 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 = 6;

  // The total number of Observations received for the window of size
  // |window_size| ending on |date|, 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 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_COUNT_STATS.
//
// Gives statistics over all devices of the number of occurrences on each
// device, over a particular time window, of a particular event.
message PerDeviceCountStatsReportRow {
  // 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 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
  // "<event-code-42>".
  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.
  uint32 window_size = 5;

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

  // Percentiles: the value of |percentile_N| is the smallest count k
  // contributed by a device to this report row such that at least N percent
  // of devices reported an occurrence count 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_90 = 190;

  // 99th percentile.
  int64 percentile_99 = 199;

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