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 15syntax = "proto3"; 16 17package google.devtools.resultstore.v2; 18 19import "google/api/field_behavior.proto"; 20import "google/api/resource.proto"; 21import "google/devtools/resultstore/v2/common.proto"; 22import "google/devtools/resultstore/v2/coverage.proto"; 23import "google/devtools/resultstore/v2/coverage_summary.proto"; 24import "google/devtools/resultstore/v2/file.proto"; 25import "google/devtools/resultstore/v2/file_processing_error.proto"; 26 27option go_package = "google.golang.org/genproto/googleapis/devtools/resultstore/v2;resultstore"; 28option java_multiple_files = true; 29option java_outer_classname = "InvocationProto"; 30option java_package = "com.google.devtools.resultstore.v2"; 31 32// An Invocation typically represents the result of running a tool. Each has a 33// unique ID, typically generated by the server. Target resources under each 34// Invocation contain the bulk of the data. 35message Invocation { 36 option (google.api.resource) = { 37 type: "resultstore.googleapis.com/Invocation" 38 pattern: "invocations/{invocation}" 39 }; 40 41 // The resource ID components that identify the Invocation. 42 message Id { 43 // The Invocation ID. 44 string invocation_id = 1; 45 } 46 47 // The resource name. Its format must be: 48 // invocations/${INVOCATION_ID} 49 string name = 1; 50 51 // The resource ID components that identify the Invocation. They must match 52 // the resource name after proper encoding. 53 Id id = 2; 54 55 // The aggregate status of the invocation. 56 StatusAttributes status_attributes = 3; 57 58 // When this invocation started and its duration. 59 Timing timing = 4; 60 61 // Attributes of this invocation. 62 InvocationAttributes invocation_attributes = 5; 63 64 // The workspace the tool was run in. 65 WorkspaceInfo workspace_info = 6; 66 67 // Arbitrary name-value pairs. 68 // This is implemented as a multi-map. Multiple properties are allowed with 69 // the same key. Properties will be returned in lexicographical order by key. 70 repeated Property properties = 7; 71 72 // A list of file references for invocation level files. 73 // The file IDs must be unique within this list. Duplicate file IDs will 74 // result in an error. Files will be returned in lexicographical order by ID. 75 // Use this field to specify build logs, and other invocation level logs. 76 // 77 // Files with the following reserved file IDs cause specific post-processing 78 // or have special handling. These files must be immediately available to 79 // ResultStore for processing when the reference is uploaded. 80 // 81 // build.log: The primary log for the Invocation. 82 // coverage_report.lcov: Aggregate coverage report for the invocation. 83 repeated File files = 8; 84 85 // Summary of aggregate coverage across all Actions in this Invocation. 86 // If missing, this data will be populated by the server from the 87 // coverage_report.lcov file or the union of all ActionCoverages under this 88 // invocation (in that order). 89 repeated LanguageCoverageSummary coverage_summaries = 9; 90 91 // Aggregate code coverage for all build and test Actions within this 92 // Invocation. If missing, this data will be populated by the server 93 // from the coverage_report.lcov file or the union of all ActionCoverages 94 // under this invocation (in that order). 95 AggregateCoverage aggregate_coverage = 10; 96 97 // NOT IMPLEMENTED. 98 // ResultStore will read and parse Files with reserved IDs listed above. Read 99 // and parse errors for all these Files are reported here. 100 // This is implemented as a map, with one FileProcessingErrors for each file. 101 // Typically produced when parsing Files, but may also be provided directly 102 // by clients. 103 repeated FileProcessingErrors file_processing_errors = 11; 104} 105 106// If known, represents the state of the user/build-system workspace. 107message WorkspaceContext {} 108 109// Describes the workspace under which the tool was invoked, this includes 110// information that was fed into the command, the source code referenced, and 111// the tool itself. 112message WorkspaceInfo { 113 // Data about the workspace that might be useful for debugging. 114 WorkspaceContext workspace_context = 1; 115 116 // Where the tool was invoked 117 string hostname = 3; 118 119 // The client's working directory where the build/test was run from. 120 string working_directory = 4; 121 122 // Tools should set tool_tag to the name of the tool or use case. 123 string tool_tag = 5; 124 125 // The command lines invoked. The first command line is the one typed by the 126 // user, then each one after that should be an expansion of the previous 127 // command line. 128 repeated CommandLine command_lines = 7; 129} 130 131// The command and arguments that produced this Invocation. 132message CommandLine { 133 // A label describing this command line. 134 string label = 1; 135 136 // The command-line tool that is run: argv[0]. 137 string tool = 2; 138 139 // The arguments to the above tool: argv[1]...argv[N]. 140 repeated string args = 3; 141 142 // The subcommand that was run with the tool, usually "build" or "test". 143 // For example, in the Bazel command "bazel build //foo", this would be set 144 // to "build". Omit if the tool doesn't accept a subcommand. This is must 145 // be a reference to one of values in args. 146 string command = 4; 147} 148 149// Attributes that apply to all invocations. 150message InvocationAttributes { 151 // Immutable. The Cloud Project that owns this invocation (this is different 152 // than the Consumer Cloud Project that calls this API). This must be set in 153 // the CreateInvocation call, and can't be changed. As input, callers can set 154 // this field to a project id (string) or a stringified int64 project number. 155 // As output, the API populates this field with the stringified int64 project 156 // number (per https://google.aip.dev/cloud/2510). 157 string project_id = 1 [(google.api.field_behavior) = IMMUTABLE]; 158 159 // The list of users in the command chain. The first user in this sequence 160 // is the one who instigated the first command in the chain. For example, 161 // this might contain just the user that ran a Bazel command, or a robot 162 // that tested a change as part of a CI system. It could also contain the user 163 // that manually triggered a CI test, then the robot that ran the test. 164 repeated string users = 2; 165 166 // Labels to categorize this invocation. 167 // This is implemented as a set. All labels will be unique. Any duplicate 168 // labels added will be ignored. Labels will be returned in lexicographical 169 // order. Labels should be a list of words describing the Invocation. Labels 170 // should be short, easy to read, and you shouldn't have more than a handful. 171 // Labels should not be used for unique properties such as unique IDs. Use 172 // properties in cases that don't meet these conditions. 173 repeated string labels = 3; 174 175 // This field describes the overall context or purpose of this invocation. 176 // It will be used in the UI to give users more information about 177 // how or why this invocation was run. 178 string description = 4; 179 180 // If this Invocation was run in the context of a larger Continuous 181 // Integration build or other automated system, this field may contain more 182 // information about the greater context. 183 repeated InvocationContext invocation_contexts = 6; 184 185 // Exit code of the process that ran the invocation. A non-zero value 186 // means failure. For example, the exit code of a "bazel test" command. 187 int32 exit_code = 7; 188} 189 190// Describes the invocation context which includes a display name and URL. 191message InvocationContext { 192 // A human readable name for the context under which this Invocation was run. 193 string display_name = 1; 194 195 // A URL pointing to a UI containing more information 196 string url = 2; 197} 198