analyzer/report_master/report_master.proto

// 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 "observation_batch.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;
}