Logging the spawn graph on demand. First step on #4891.

This is a very heavy and slow option by design. It will be enabled only when a user wants to debug their build, most frequently to compare the step-by-step results of two builds.

TESTED: manually on various rules, including directories.
RELNOTES: None
PiperOrigin-RevId: 193539034

2 files changed, 123 insertions, 0 deletions

diff --git a/src/main/protobuf/BUILD b/src/main/protobuf/BUILD
index cb44e63d8c..684dcb2e73 100644
--- a/src/main/protobuf/BUILD
+++ b/src/main/protobuf/BUILD
@@ -27,6 +27,7 @@ FILES = [
     "invocation_policy",
     "java_compilation",
     "plmerge",
+    "spawn",
     "test_status",
     "worker_protocol",
 ]
diff --git a/src/main/protobuf/spawn.proto b/src/main/protobuf/spawn.proto
new file mode 100644
index 0000000000..b6c6ec36d5
--- /dev/null
+++ b/src/main/protobuf/spawn.proto
@@ -0,0 +1,122 @@
+// Copyright 2018 The Bazel Authors. All rights reserved.
+//
+// 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 tools.protos;
+
+option java_package = "com.google.devtools.build.lib.exec";
+option java_outer_classname = "Protos";
+
+message Digest {
+  // Digest of a file's contents using the current FileSystem digest function.
+  string hash = 1;
+
+  // The size in bytes of the original content.
+  int64 size_bytes = 2;
+
+  // The digest function that was used to generate the hash.
+  // This is not an enum for compatibility reasons, and also because the
+  // purpose of these logs is to enable analysis by comparison of multiple
+  // builds. So, from the programmatic perspective, this is an opaque field.
+  string hash_function_name = 3;
+}
+
+message File {
+  // Path to the file relative to the execution root.
+  string path = 1;
+
+  // Digest of the file's contents.
+  Digest digest = 2;
+}
+
+// Contents of command environment.
+message EnvironmentVariable {
+  string name = 1;
+  string value = 2;
+}
+
+// Command execution platform. This message needs to be kept in sync
+// with [Platform][google.devtools.remoteexecution.v1test.Platform].
+message Platform {
+  message Property {
+    string name = 1;
+    string value = 2;
+  }
+  repeated Property properties = 1;
+}
+
+// Details of an executed spawn.
+// These will only be generated on demand, using the
+// --execution_log_file=<path> flag.
+// Each message contains an executed command, its full inputs and outputs.
+// The purpose of these is to enable comparisons of multiple builds to diagnose
+// output differences or more subtle problems such as remote caching misses.
+// Only the executed Spawns will be output -- local cache hits are ignored.
+message SpawnExec {
+  // The command that was run.
+  repeated string command_args = 1;
+
+  // The command environment.
+  repeated EnvironmentVariable environment_variables = 2;
+
+  // The command execution platform.
+  Platform platform = 3;
+
+  // The inputs at the time of the execution.
+  repeated File inputs = 4;
+
+  // All the listed outputs paths. The paths are relative to the execution root.
+  // Actual outputs are a subset of the listed outputs. These paths are sorted.
+  repeated string listed_outputs = 5;
+
+  // Was the Spawn allowed to be executed remotely.
+  bool remotable = 6;
+
+  // Was the Spawn result allowed to be cached.
+  bool cacheable = 7;
+
+  // The Spawn timeout.
+  int64 timeout_millis = 8;
+
+  // A user-friendly text message representing the spawn progress.
+  string progress_message = 9;
+
+  // An opaque string that identifies the type of the Spawn's action.
+  string mnemonic = 10;
+
+  // The outputs generated by the execution.
+  repeated File actual_outputs = 11;
+
+  // If the Spawn was actually executed, rather than a remote cache hit,
+  // this will be the name of the runner executing the spawn, e.g. remote or
+  // linux-sandbox. Note this is not the same as the "strategy" string -- even
+  // though the action strategy may be remote, a particular action may still
+  // fall back to local execution due to a variety of reasons. This field
+  // indicates what really happened for the particular Spawn+execution.
+  string runner = 12;
+
+  // Whether the Spawn was a remote cache hit, in which case it was not executed
+  // and the runner field will be empty.
+  bool remote_cache_hit = 13;
+
+  // A text status returned by the execution, in case there were any errors.
+  // Empty in case of successful execution.
+  string status = 14;
+
+  // This field contains the contents of SpawnResult.exitCode.
+  // Its semantics varies greatly depending on the status field.
+  // Dependable: if status is empty, exit_code is guaranteed to be zero.
+  int32 exit_code = 15;
+}