| // 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 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 prefix to use for the generated object names within the bucket. |
| // This is optional. Often it is desirable to use a prefix that |
| // is like a folder path, i.e. foo/bar/baz/. If this is not empty, Cobalt |
| // will add a trailing forward slash "/" if the string does not end |
| // with a forward slash. |
| string folder_path = 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; |
| |
| // The type of epoch to use when aggregating Observations for a report. |
| // This also determines the frequency of generating reports. |
| EpochType aggregation_epoch_type = 9; |
| |
| // 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 = 10; |
| |
| DifferentialPrivacyConfig dp_config = 11; |
| |
| // If this list is non-empty, then reports for this ReportConfig that are |
| // 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. |
| repeated ReportExportConfig export_configs = 12; |
| } |
| |
| // 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; |
| } |
| |