observation_batch.proto

// Copyright 2018 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
syntax = "proto3";

package cobalt;

option go_package = "cobalt";

import "encrypted_message.proto";

////////////////////////////////////////////////////////////////////////////////
//
// NOTE: This copy of observation_batch.proto is used by the Cobalt client.
// A second copy of this file is used by the Cobalt Shuffler and Analyzer
// running in Google production. It is necessary to have two copies due to
// requirements by the Google Logs Privacy team regarding the location of
// of .proto files used in logs processing pipelines. Any changes to this
// file must be replicated in the other copy of the file.
//
////////////////////////////////////////////////////////////////////////////////

// The state of a single experiment on a device.
message Experiment {
  // The id of the experiment as defined by the Experiment framework.
  int64 experiment_id = 1;
  // The id of the experiment arm as defined by the Experiment framework.
  int64 arm_id = 2;
}

// A SystemProfile describes the client system on which an Observation is
// collected.
message SystemProfile {
  reserved 3;

  enum OS {
    UNKNOWN_OS = 0;
    FUCHSIA = 1;
    LINUX = 2;
  }

  enum ARCH {
    UNKNOWN_ARCH = 0;
    X86_64 = 1;
    ARM_64 = 2;
  }

  OS os = 1;
  ARCH arch = 2;

  // This is a string representing the board name of the device. If a board name
  // cannot be determined, then this field will be 'unknown:<cpu signature>'.
  string board_name = 4;

  // This is a string representing the type of Fuchsia product from which
  // an observation is collected.
  //
  // During development, this is going to refer to layers of the Fuchsia cake
  // such as "garnet", "zircon", "topaz", etc... In the future, we will use
  // something related to what sort of device we are running on, such as
  // "Acme Lightbulb X" or "Machine Corp. Laptop III".
  string product_name = 5;

  // This is a string representing the version of the currently running system.
  // The use of this field is system-specific. For example on Fuchsia a possible
  // value for |version| is "20190220_01_RC00".
  string system_version = 8;

  // Contains all the experiments the device has a notion of and the experiment
  // state the device belongs to.
  repeated Experiment experiments = 7;

  // We used to have  a field called |build_level|.
  reserved 6;
  reserved "build_level";
}

// ObservationMetadata describes the parts of an observation other than the
// secret payload.
message ObservationMetadata {
  // next id: 8

  // An Observation is for a particular Metric.
  // The following three values together specify that metric.
  uint32 customer_id = 1;
  uint32 project_id = 2;
  uint32 metric_id = 3;

  // Starting in Cobalt 1.0 an Observation is for a particular Report.
  // The tuple (customer_id, project_id, metric_id, report_id) specifies the
  // Report.
  uint32 report_id = 7;

  // The day on which the observation occurred, expressed as the zero-based
  // index relative to January 1, 1970.
  // i.e. 0 = January 1, 1970
  //      1 = January 2, 1970
  //      etc.
  //
  // We intentionally leave the meaning of this vague and leave it to each
  // Encoder Client to define how to make it precise. Which day it is depends on
  // time zone. The Encoder client is free to use the local time zone or a
  // different time zone. The Encoder client is free to add some random noise to
  // the time at which an event occurred and this might change the day.
  uint32 day_index = 4;

  // The profile of the client system on which the Observation was collected.
  SystemProfile system_profile = 5;

  // We used to have  a field called |backend|.
  reserved 6;
  reserved "backend";
}

// A batch of encrypted Observations with common metadata.
// The Observations are encrypted to the public key of an Analyzer so the
// Shuffler cannot read them. |Observation| is defined in observation.proto.
//
// ObservationBatches are used for both input to and output from the Shuffler.
// As input they are organized into Envelopes, each Envelope coming from some
// client device. |Envelope| is defined in envelope.proto
//
// The output from the Shuffler consists of shuffled ObservationBatches, each
// ObservationBatch consisting of Observations from many clients.
message ObservationBatch {
  // The common Metadata for all of the encrypted observations in this batch.
  ObservationMetadata meta_data = 1;

  // Each EncryptedMessage contains the ciphertext of an Observation that has
  // been encrypted to the public key of the Analyzer.
  repeated EncryptedMessage encrypted_observation = 2;
}