| // 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; |
| |
| import "config/encodings.proto"; |
| |
| option go_package = "config"; |
| |
| message DifferentialPrivacyConfig { |
| float epsilon = 1; |
| float delta = 2; |
| } |
| |
| // A list of candidates to use during a string RAPPOR analysis. |
| message RapporCandidateList { |
| repeated string candidates = 1; |
| } |
| |
| // Human-readable labels to associate with the rows of a report for a |
| // metric variable of type INDEX. Values of this type are zero-based indices |
| // into some enumerated set defined outside of the Cobalt configuration system. |
| message IndexLabels { |
| // The keys to the map are the zero-based indices and |
| // the values are human-readable labels to be used in the report. |
| // A missing label is NOT a fatal error. If an index occurs in the data but |
| // there is no corresponding label specified here then the generated report |
| // will contain a string such as "<index 42>." |
| map<uint32, string> labels = 1; |
| } |
| |
| // 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; |
| |
| // This field will be populated only if the corresponding metric part |
| // is of type INDEX. |
| IndexLabels index_labels = 2; |
| |
| // This field will be populated only if the corresponding metric part |
| // is of type STRING and if the report is expected to include some |
| // string RAPPOR analysis. |
| RapporCandidateList rappor_candidates = 3; |
| } |
| |
| // The different types of reports that Cobalt knows how to create. Each |
| // ReportConfig specifies one ReportType in its |report_type| field. |
| // |
| // The number of variables that occur in the ReportConfig's |variable| field |
| // must be consistent with the ReportType. |
| // |
| // Not every ReportType is consistent with every kind of encoding. If an |
| // observation occurs in the set of observations being analyzed whose |
| // encoding is not consistent with the ReportType then the report generation |
| // may fail. |
| enum ReportType { |
| // A single-variable histogram report. Exactly one variable must appear in |
| // the |variable| field. Each row of the report presents a value and an |
| // estimate of the count of observations in the analysis set that contain |
| // that value. |
| // |
| // All encoding types are supported but in the current version of Cobalt |
| // the set of observations being analyzed must be homogeneous with respect to |
| // the encoding. |
| HISTOGRAM = 0; |
| |
| // A joint two-variable histogram report. Exactly two variables must appear |
| // in the |variable| field. Each row of the report presents two values and an |
| // estimate of the count of observations in the analysis set that contain |
| // those two values. |
| // |
| // A report of this type will be dependent on the two one-way marginal reports |
| // being generated prior to the generation of this report. When a report of |
| // this type is requested by a user, the Cobalt system will arrange for the |
| // two one-way marginals to also be generated--the user does not have to |
| // explicitly request those. The association between the joint report and |
| // its two one-way marginals will be captured via the |associated_report_ids| |
| // field of |ReportMetadata|. |
| // |
| // Only the String RAPPOR and Basic RAPPOR encoding types are supported. |
| JOINT = 1; |
| |
| // A raw dump of the input observations. No aggregation, analysis or |
| // differentially private release will be performed. The report rows will |
| // not be stored in the ReportStore so they may not be retrieved later |
| // via a GetReport() operation. At report generation time the raw dump will |
| // be serialized and exported to an external system if one or more |
| // ReportExportConfigs are specified in the ReportConfig. The external system |
| // may then be used to perform aggregation and analysis. |
| // |
| // Raw Dump reports should be used in Cobalt only as a last resort if none |
| // of Cobalt's built-in report types will serve your purpose. As Raw Dump |
| // reports provide the ability to perform arbitrary, ad hoc, ex post facto |
| // aggregation and querying, they may also be a good solution for temporary |
| // exploration with an eye towards eventually replacing the Raw Dump report |
| // with one of Cobalt's built-in report types. |
| // |
| // In more detail, a raw dump report is a report on any number of variables |
| // in which each input ObservationPart must use the NoOp encoding so that it |
| // contains an unencoded ValuePart. There will be one output report row for |
| // each input observation and each output report row will contain a copy of |
| // the ValueParts from the input ObservationParts, in the order specified by |
| // the |variable|s in the ReportConfig. |
| RAW_DUMP = -1; |
| } |
| |
| // A specification of how and where to export a Cobalt report to some external |
| // system. |
| message ReportExportConfig { |
| // A specification of how to serialize the report for export. |
| oneof export_serialization { |
| // Export as CSV |
| CSVSerializationConfig csv = 1; |
| } |
| // A specification of the location to which the report should be exported. |
| oneof export_location { |
| // Export to Google Cloud Storage. |
| GCSExportLocation gcs = 2; |
| } |
| } |
| |
| // A specification of how to export a report as a CSV file. |
| message CSVSerializationConfig { |
| } |
| |
| // A specification of a location within Google Cloud Storage where a report |
| // should be exported. |
| message GCSExportLocation { |
| // The name of a GCS bucket |
| string bucket = 1; |
| } |
| |
| // A specification of how to schedule the execution of a report. |
| message ReportSchedulingConfig { |
| // The type of epoch to use when aggregating Observations for a report. |
| // This also determines the frequency of generating reports. |
| EpochType aggregation_epoch_type = 1; |
| |
| // The number of days to wait before considering a report finalized. The |
| // The ReportScheduler may re-generate a report multiple times in case |
| // additional observations trickle in several days after the period ends. |
| // This is important for several reasons: (a) The client and server may use |
| // different time zones (b) The client may be temporarily offline (c) the |
| // Shuffler may be configured to intentionally add a delay. This setting |
| // controls the number of days before the ReportScheduler considers the report |
| // to be finalized. Usually a good value for this field is 3, but this may be |
| // decreased or increased based on special circumstances. Larger values |
| // cause the ReportScheduler to do more work by re-generating the same report |
| // multiple times. |
| // This value must be an integer in the range [0, 20]. |
| uint32 report_finalization_days = 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; |
| |
| // Which type of report is this? |
| ReportType report_type = 7; |
| |
| // The variables being analyzed in this report. The number of variables must |
| // be consistent with the type of report. |
| repeated ReportVariable variable = 8; |
| |
| |
| DifferentialPrivacyConfig dp_config = 9; |
| |
| // If this field is set it means that the ReportMaster should generate reports |
| // for this ReportConfig automatically on a recurring schedule. The field |
| // |export_configs| below should also be set in order to cause the |
| // automatically generated reports to be exported. |
| ReportSchedulingConfig scheduling = 10; |
| |
| // If this list is non-empty, then reports for this ReportConfig that are |
| // automatically generated by the Report Scheduler (but not one-off reports) |
| // will, in addition to being saved in the ReportStore, also be exported to |
| // one or more external systems as specified. The field |scheduling| above |
| // should also be set in order to enable the automatic generation of |
| // reports. |
| repeated ReportExportConfig export_configs = 11; |
| } |
| |
| // 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; |
| } |
| |