config/report_configs.proto - cobalt - Git at Google

 // 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";
 import "config/metrics.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 {
   // Next ID: 13

   // 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 list of SystemProfileFields to include in each row of the report.
   repeated SystemProfileField system_profile_field = 12;

   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;
 }
	// 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";
	import "config/metrics.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 {
	// Next ID: 13

	// 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 list of SystemProfileFields to include in each row of the report.
	repeated SystemProfileField system_profile_field = 12;

	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;
	}