| // Copyright 2017 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.analyzer; |
| |
| option go_package = "report_master"; |
| |
| import "observation.proto"; |
| import "config/report_configs.proto"; |
| import "google/protobuf/timestamp.proto"; |
| |
| // A Report is the final output of the Cobalt pipeline. The ReportMaster |
| // is the component of Cobalt that orchestrates and schedules the generation |
| // of reports. |
| // |
| // ReportMaster service is used by Cobalt customers to generate one-off |
| // reports, to query the set of reports that exist, and to fetch individual |
| // reports. Note that in the primary use of Cobalt report generation occurs |
| // automatically on a regular schedule and there is no reason to request the |
| // generation of a one-off report. This interface may be used to query and |
| // fetch both one-off, manually-requested reports and regularly scheduled |
| // reports. |
| service ReportMaster { |
| // Requests that the ReportMaster start to generate a new one-off report. The |
| // |report_id| returned in the response may be used to query the progress |
| // and results. Note: This method may not be used to start a RAW_DUMP |
| // report. Those may only be started via Cobalt's Report Scheduler. |
| rpc StartReport(StartReportRequest) returns (StartReportResponse) { |
| } |
| |
| // Fetches a report and its metadata by ID. If the report generation is not |
| // yet complete then only the metadata is returned. |
| rpc GetReport(GetReportRequest) returns (Report) { |
| } |
| |
| // Queries for the list of all reports that exist in the system for the |
| // specified ReportConfig that were created over the specified time span. |
| // Uses server streaming to return the results. The results are returned in |
| // chronological order of report creation time. |
| rpc QueryReports(QueryReportsRequest) returns (stream QueryReportsResponse) { |
| } |
| } |
| |
| // The request message for StartReport. |
| message StartReportRequest { |
| // The (customer_id, project_id, report_config_id) triple specifies the |
| // ID of the ReportConfig that the generated report will be based on. |
| // ReportConfigs are registered in the Cobalt config system. |
| uint32 customer_id = 1; |
| uint32 project_id = 2; |
| uint32 report_config_id = 3; |
| |
| // The report will analyze the set of Observations that have been tagged with |
| // a day index that falls within the interval |
| // [first_day_index, last_day_index]. Day indices in Cobalt are zero-based |
| // with day zero being January 1, 1970. |
| uint32 first_day_index = 4; |
| uint32 last_day_index = 5; |
| } |
| |
| // The response message for StartReport. |
| message StartReportResponse { |
| // The unique identifier for the new report whose generation has begun. Use |
| // this to query the state of the report generation, to fetch metadata about |
| // the report being generated and to fetch the results when the generation is |
| // complete. |
| string report_id = 1; |
| } |
| |
| // The request message for GetReport. |
| message GetReportRequest { |
| // The ID of the report to get. |
| string report_id = 1; |
| } |
| |
| // The response message for GetReport. |
| message Report { |
| // The metadata for the report. |
| ReportMetadata metadata = 1; |
| |
| // The rows of the report. This will only be populated if the |state| |
| // of the report in the ReportMetadata is |COMPLETED_SUCCESSFULLY|. |
| // |
| // There are different types of reports and correspondingly different |
| // types of report rows. The type of this report is specified by the |
| // |report_type| field within |metadata|. All of the ReportRows in |
| // |rows| must be of the corresponding type. |
| ReportRows rows = 2; |
| } |
| |
| // The rows of a report. |
| message ReportRows { |
| repeated ReportRow rows = 1; |
| } |
| |
| // Metadata about an instance of a report. |
| message ReportMetadata { |
| // The unique ID of this report. |
| string report_id = 1; |
| |
| // (customer_id, project_id, report_config_id) together specify which |
| // ReportConfig this is a report for. |
| uint32 customer_id = 2; |
| uint32 project_id = 3; |
| uint32 report_config_id = 4; |
| |
| // The current state of the report generation. |
| ReportState state = 5; |
| |
| // The time that the generation of this report was first initialized, |
| // as recorded by the server. This may be different than |start_time| if |
| // the report was initially in the WAITING_TO_START state. |
| google.protobuf.Timestamp creation_time = 6; |
| |
| // The time that the generation of this report began, as recorded by the |
| // server. |
| google.protobuf.Timestamp start_time = 7; |
| |
| // The time that the generation of this report completed, as recorded by the |
| // server. This is unset if the state is IN_PROGRESS. |
| google.protobuf.Timestamp finish_time = 8; |
| |
| // This report analyzes Observations with a day_index in the range |
| // [first_day_index, last_day_index] |
| uint32 first_day_index = 9; |
| uint32 last_day_index = 10; |
| |
| // The type of report that this is. This may be different from the type |
| // of report specified in the ReportConfig if this report is an auxilliary |
| // report automatically generated by the system in support of the primary |
| // report. For example if the primary report type was JOINT this report may |
| // be one of the automatically generated one-way marginal reports in which |
| // case its type would be HISTOGRAM. |
| ReportType report_type = 11; |
| |
| // The names of the metric parts analyzed in this report. |
| repeated string metric_parts = 12; |
| |
| // The IDs of associated reports, if any. For example if this is a joint |
| // two-variable report this field will contain the IDs of the two one-way |
| // marginal reports. |
| repeated string associated_report_ids = 13; |
| |
| // Is this a one-off report that was explicitly requested via the |
| // StartReport method as opposed to being generated by regular periodic |
| // report scheduling? This is purely for informational purposes and has no |
| // other bearing on the report. |
| bool one_off = 14; |
| |
| // Any human-readable messages directed toward the report consumer that |
| // were produced by the server during the generation of the report. |
| repeated InfoMessage info_messages = 15; |
| |
| // Are the rows of this report stored in the ReportStore? In some cases |
| // the ReportMaster will generate a report soley for the purpose of |
| // serializing and exporting the report rows and will not store the |
| // report rows in the Report Store. |
| bool in_store = 16; |
| } |
| |
| // The request message for QueryReports. |
| message QueryReportsRequest { |
| // The (customer_id, project_id, report_config_id) triple specify the |
| // ID of the ReportConfig whose reports are being queried. ReportConfigs |
| // are registered in the Cobalt config system. |
| uint32 customer_id = 1; |
| uint32 project_id = 2; |
| uint32 report_config_id = 3; |
| |
| // The query is restricted to reports whose |creation_time| falls in the |
| // interval of time [first_timestamp, limit_timestamp). Note that this is |
| // unrelated to the day_indices of the Observations that the reports analyze. |
| google.protobuf.Timestamp first_timestamp = 4; |
| google.protobuf.Timestamp limit_timestamp = 5; |
| } |
| |
| // The response message for QueryReports. These will be streamed back by the |
| // server in chronological order of |creation_time|. |
| message QueryReportsResponse { |
| // The ReportMetadata are sorted by |creation_time|. |
| repeated ReportMetadata reports = 1; |
| } |
| |
| // A single row of a report. As there are different types of reports, there |
| // are different types of ReportRows. A report of a given type will contain |
| // only rows of the corresponding type. |
| message ReportRow { |
| oneof row_type { |
| HistogramReportRow histogram = 1; |
| JointReportRow joint = 2; |
| RawDumpReportRow raw_dump = 999999; |
| } |
| } |
| |
| // A single row of a HISTOGRAM report. |
| message HistogramReportRow { |
| // Next ID: 6 |
| |
| // The value for this row. |
| ValuePart value = 1; |
| |
| // An additional human-readable label used to identify this row. |
| // This may be empty if |value| contains all the information necessary to |
| // identify this row. One case in which this will be populated is if |
| // |value| contains an |index_value| and the ReportConfig used to generate |
| // this report contained a human-readable label for the index. |
| string label = 4; |
| |
| // The SystemProfile for this row. This will be populated with only the fields |
| // that are specified in the |system_profile_field| entry in the ReportConfig. |
| SystemProfile system_profile = 5; |
| |
| // This field is the primary output of Cobalt Analysis. It is an estimate |
| // of the true count of the value in the user population. |
| float count_estimate = 2; |
| |
| // 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_error = 3; |
| } |
| |
| // A single row of a JOINT report. |
| message JointReportRow { |
| // TODO(rudominer) Implement Joint reports. |
| } |
| |
| // A single row of a RAW_DUMP report. It contains a copy of some of the |
| // unencoded values from an input Observation. |
| message RawDumpReportRow { |
| // Each of these values is a copy of the ValuePart from one of the |
| // ObservationParts of one of the input Observations. The ObservationPart must |
| // have used the NoOp encoding. The order of the values here corresponds to |
| // the order of the |variable|s in the ReportConfig. |
| repeated ValuePart values = 1; |
| |
| // The SystemProfile for this row. This will be populated with only the fields |
| // that are specified in the |system_profile_field| entry in the ReportConfig. |
| SystemProfile system_profile = 5; |
| } |
| |
| // What state is the report generation in? |
| enum ReportState { |
| // The report generation is waiting for some condition before it can start. |
| // One example is that a joint two-variable report needs to wait for the |
| // one-way marginal reports to complete before it can start. The |
| // |info_messages| field of ReprtMetadata may have more information. |
| WAITING_TO_START = 0; |
| |
| // The report generation is in progress. |
| IN_PROGRESS = 1; |
| |
| // The report generation has completed successfully. |
| COMPLETED_SUCCESSFULLY = 2; |
| |
| // The report generation terminated without completing successfully. |
| // More information may be found in the |info_message|. |
| TERMINATED = 3; |
| } |
| |
| // A human-readable message generated by the server during the generation |
| // of the report. |
| message InfoMessage { |
| google.protobuf.Timestamp timestamp = 1; |
| string message = 2; |
| } |