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 }