config/report_configs.proto

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

import "encodings.proto";

package cobalt;

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

// A ReportVariable is used within a |ReportConfig|. It specifies that
// a generated report should include a named part of a metric and it
// gives additional information necessary to analyze that metric part.
message ReportVariable {
  // The named part of the metric to include in the report.
  string metric_part = 1;

  // In case the report includes a String RAPPOR analysis, this field gives
  // the Analyzer a hint about where to find the RAPPOR map file.
  string candidate_map_location = 2;
}

// A ReportConfig describes to the Analyzer a particular report to produce.
// A report is for a particular metric.
message ReportConfig {
  // These three numbers form this ReportConfig's unique ID in the Cobalt Config
  // DB.
  uint32 customer_id = 1;
  uint32 project_id = 2;
  uint32 id = 3;

  // e.g. "Fuchsia Usage by Hour"
  string name = 4;

  // e.g. "Whenever a Fuchsia device is woken up from sleep we capture the
  //  hour of the day."
  string description = 5;

  // The customer_id, project_id and metric_id refer to the metric that this
  // is a report of.
  uint32 metric_id = 6;

  // This field must contain either one or two values which specify the parts
  // of the Metric to include in the report. If there is a single value that
  // indicates a univariate analysis of the specified variable.
  // If there are two values that specifies a Correlation Analysis between
  // the two variables.
  repeated ReportVariable variable = 7;

  // The type of epoch to use when aggregating Observations for a report.
  // This also determines the frequency of generating reports.
  EpochType aggregation_epoch_type = 8;

  // The number of days after an epoch ends before a report analyzing that
  // epoch should be run. For example if |aggregation_epoch_type| = WEEK
  // and report_delay_days = 3 then an analyis will be executed and a report
  // will be generated every Tuesday for the 7 day period ending on the Saturday
  // three days prior to the report day.
  uint32 report_delay_days = 9;

  DifferentialPrivacyConfig dp_config = 10;
}

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