github.com/distbuild/reclient@v0.0.0-20240401075343-3de72e395564/experiments/api/experiment/experiment.proto (about)

     1  // Copyright 2023 Google LLC
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  syntax = "proto3";
    16  
    17  package experiment;
    18  
    19  import "api/log/log.proto";
    20  import "api/stat/stat.proto";
    21  import "api/stats/stats.proto";
    22  
    23  // Experiment encapsulates all configuration required for running an experiment
    24  // on reclient in GCE.
    25  message Experiment {
    26    // The name of the experiment.
    27    string name = 1;
    28  
    29    // The base configuration for all run configurations of the experiment.
    30    RunConfiguration base_configuration = 2;
    31  
    32    // The list of run configurations in the experiment. Configurations in this
    33    // list are applied on top of the base configuration. Any non-repeated field
    34    // is replaced by the values in run configuration, and any repeated field is
    35    // appended to by the values in the run configuration.
    36    repeated RunConfiguration run_configurations = 3;
    37  
    38    // The number of trials to run.
    39    int32 num_trials = 4;
    40  
    41    // Tags to add to the experiment run.
    42    map<string, string> tags = 5;
    43  }
    44  
    45  // A configuration for a run or a set of runs in an experiment.
    46  message RunConfiguration {
    47    // The name of the run configuration.
    48    string name = 1;
    49  
    50    // The settings of the VM to use in the configuration.
    51    oneof machine_settings {
    52      VMSettings vm_settings = 2;
    53      WSSettings ws_settings = 14;
    54    }
    55  
    56    // Can either be "local" or path to a directory in GCS that contains reclient
    57    // binaries. When "local" is used, the framework uses locally built version of
    58    // re-client binaries.
    59    string reclient_bin_path = 3;
    60  
    61    // The location on the VM to which the reclient binaries should be
    62    // downloaded.
    63    string reclient_destination = 4;
    64  
    65    // List of inputs to be moved to the GCE machine before it happens.
    66    repeated Input inputs = 11;
    67  
    68    // List of commands to run for the setup of the run configuration. Only runs
    69    // once for all trials.
    70    repeated Command setup_commands = 6;
    71  
    72    // List of pre-build commands to run before building. Runs once per trial. If
    73    // a command has a user switch 'su', every build command following that runs
    74    // as the desired user.
    75    repeated Command pre_build_commands = 7;
    76  
    77    // The build command to run and measure timing for.
    78    Command build_command = 8;
    79  
    80    // List of post-build commands to run after building, before downloading
    81    // outputs and teardown. Runs once per trial. Similar to pre_build_commands,
    82    // if any of them has a user switch `su`, every command afterwards will run
    83    // as the desired user.
    84    repeated Command post_build_commands = 12;
    85  
    86    // List of output file paths to download from the VM after a trial. If the
    87    // file is under the attached disk, it will be under /img.
    88    repeated string outputs = 9;
    89  
    90    // List of teardown commands to run at the end of a trial.
    91    repeated Command teardown_commands = 10;
    92  
    93    // Number of machines to run this config. Defaults to 1. Must be positibe.
    94    uint32 num_machines = 13;
    95  
    96    // Environment variables that are build settings.
    97    repeated Environment environment = 15;
    98  
    99    reserved 5;
   100  
   101    // Next ID: 16
   102  }
   103  
   104  // Inputs to be copied over from your local machine to the GCE workstations.
   105  message Input {
   106    // Source path relative to the experiment textproto location.
   107    string source = 1;
   108    // Destination path in the GCE machine.
   109    string destination = 2;
   110    // By default, the file is uploaded to GCS and then downloaded in each remote
   111    // machine, saving all data that makes the experiment reproducible.
   112    //
   113    // If the file isn't worth preserving or is sensitive, setting this to true
   114    // bypasses GCS and sends the file straight to the VMs.
   115    bool vm_direct = 3;
   116  }
   117  
   118  // Settings for the VM.
   119  // A virtual machine will be created for the experiment to run,
   120  // and then deleted when the experiment has completed successfully.
   121  message VMSettings {
   122    // Zone to create the VM in.
   123    string zone = 1;
   124  
   125    // The machine type of the VM.
   126    string machine_type = 2;
   127  
   128    // The name of the image to use to create the VM.
   129    string image = 3;
   130  
   131    // The GCP project where the image exists.
   132    string image_project = 4;
   133  
   134    enum OS {
   135      LINUX = 0;
   136      WINDOWS = 1;
   137      // Next ID: 2
   138    }
   139  
   140    // The OS for the image being ran. Defaults to linux.
   141    OS image_os = 8;
   142  
   143    // Extra flags to add to the VM creation command.
   144    repeated string creation_flags = 5;
   145  
   146    // The size of the system disk should be resized to.
   147    // If not provided default disk size from the snapshot is used.
   148    // The value must be a whole number followed by a size unit of GB for gigabyte, or TB for terabyte.
   149    // If no size unit is specified, GB is assumed.
   150    // For example, 10GB will produce 10 gigabyte disks. Disk size must be a multiple of 1 GB.
   151    string system_disk_size = 12;
   152  
   153    // The name of the disk image to attach to the VM.
   154    string disk_image = 6;
   155  
   156    // The GCP project where the disk image exists.
   157    string disk_image_project = 7;
   158  
   159    // The data disk type. Defaults to pd-ssd.
   160    string disk_type = 11;
   161  
   162    // Path to ssh private key to be used. The VM image is expected to have the
   163    // public key pre-installed.  Setting this removes the gcloud prefix.
   164    string ssh_key_path = 9;
   165  
   166    // SSH user to set. This disables GCP OS login, and is required on Windows
   167    // images since they do not support OS login.
   168    string ssh_user = 10;
   169  
   170    // Next ID: 13
   171  }
   172  
   173  // Existing workstation settings.
   174  // Connect to an existing workstation/cloudtop/VM at the given address.
   175  // The target machine must be up and available.
   176  // The machine will not be started or stopped as part of the experiment.
   177  // The user must have ssh access to the machine.
   178  message WSSettings {
   179    // The address to ssh to.
   180    string address = 1;
   181  
   182    // SSH user to log in with.
   183    string ssh_user = 2;
   184  
   185    // Path to ssh private key to be used. The workstation is expected to have the
   186    // public key pre-installed.
   187    string ssh_key_path = 3;
   188  
   189    // Instructs the framework to use "sudo" for certain setup and teardown steps.
   190    // This can only work if the user has passwordless sudo access on the target machine.
   191    // Defaults to false.
   192    // Experiment writer must ensure their experiment does not require any root privileges.
   193    bool use_sudo = 4;
   194    // Next ID: 5
   195  }
   196  
   197  // Command is a command to run on the VM during an experiment.
   198  message Command {
   199    // List of command args.
   200    repeated string args = 1;
   201  }
   202  
   203  // Results of an experiment.
   204  message Results {
   205    // The name of the experiment.
   206    string name = 1;
   207  
   208    // Url of the experiment configuration in GCS.
   209    string config_url = 2;
   210  
   211    // Results per run configuration.
   212    repeated ConfigurationResult config_results = 3;
   213  }
   214  
   215  // The results collected form a configuration.
   216  message ConfigurationResult {
   217    // The name of the configuraiton.
   218    string name = 1;
   219  
   220    // The duration of trials of the configuration.
   221    repeated int64 durations = 2;
   222  
   223    // The stats collected from trials of the configuration.
   224    repeated Stats stats = 3;
   225  }
   226  
   227  // The full aggregated build stats and properties.
   228  message Stats {
   229    // Number of actions in the build.
   230    int64 num_records = 1;
   231  
   232    // Aggregated build stats.
   233    repeated stats.Stat stats = 2;
   234  
   235    // Environment variables that are build settings.
   236    repeated Environment environment = 3;
   237  
   238    // Verification results, if exist.
   239    log.Verification verification = 4;
   240  
   241    // RBE tooling version.
   242    string tool_version = 5;
   243  }
   244  
   245  // Environment is the environment variable set during the build and used by
   246  // reclient. We use a message instead of a map because bigquery does not support
   247  // inferring schema from a map.
   248  message Environment {
   249    // The environment variable key.
   250    string key = 1;
   251  
   252    // The environment variable value.
   253    string value = 2;
   254  }