src/main/protobuf/spawn.proto

// 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;

import "google/protobuf/duration.proto";

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;
}

// Timing, size, and memory statistics for a SpawnExec.
message SpawnMetrics {
  // Total wall time spent running a spawn, measured locally.
  google.protobuf.Duration total_time = 1;
  // Time taken to convert the spawn into a network request.
  google.protobuf.Duration parse_time = 2;
  // Time spent communicating over the network.
  google.protobuf.Duration network_time = 3;
  // Time spent fetching remote outputs.
  google.protobuf.Duration fetch_time = 4;
  // Time spent waiting in queues.
  google.protobuf.Duration queue_time = 5;
  // Time spent setting up the environment in which the spawn is run.
  google.protobuf.Duration setup_time = 6;
  // Time spent uploading outputs to a remote store.
  google.protobuf.Duration upload_time = 7;
  // Time spent running the subprocess.
  google.protobuf.Duration execution_wall_time = 8;
  // Time spent by the execution framework processing outputs.
  google.protobuf.Duration process_outputs_time = 9;
  // Time spent in previous failed attempts, not including queue time.
  google.protobuf.Duration retry_time = 10;
  // Total size in bytes of inputs or 0 if unavailable.
  int64 input_bytes = 11;
  // Total number of input files or 0 if unavailable.
  int64 input_files = 12;
  // Estimated memory usage or 0 if unavailable.
  int64 memory_estimate_bytes = 13;
  // Limit of total size of inputs or 0 if unavailable.
  int64 input_bytes_limit = 14;
  // Limit of total number of input files or 0 if unavailable.
  int64 input_files_limit = 15;
  // Limit of total size of outputs or 0 if unavailable.
  int64 output_bytes_limit = 16;
  // Limit of total number of output files or 0 if unavailable.
  int64 output_files_limit = 17;
  // Memory limit or 0 if unavailable.
  int64 memory_bytes_limit = 18;
  // Time limit or 0 if unavailable.
  google.protobuf.Duration time_limit = 19;
}

// 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 cache hit,
  // this will be the name of the runner executing the spawn, e.g. remote or
  // linux-sandbox. If it was a remote cache hit, the runner will be
  // "remote cache hit". If it was a local cache hit, the action will not be
  // included in the log in the first place.
  //
  // 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;

  // Was the Spawn result allowed to be cached remotely.
  bool remote_cacheable = 16;

  // The wall time it took to execute the Spawn. This is only the time spent in
  // the subprocess, not including the time doing setup and teardown.
  google.protobuf.Duration walltime = 17;

  // Canonical label of the target that emitted this spawn, may not always be
  // set.
  string target_label = 18;

  // A unique identifier for this Spawn.
  Digest digest = 19;

  // Timing, size and memory statistics.
  SpawnMetrics metrics = 20;
}

// Additional information that should be taken into account when
// computing the key of an action, thereby ensuring that actions remain
// distinct.
message CacheSalt {
  // Whether or not the action may be executed remotely, if remote
  // execution were to be enabled. This ensures that adding/removing the
  // "no-remote-exec" tag from a target forces a local/remote rebuild.
  bool may_be_executed_remotely = 1;

  // Requires the execution service do NOT share caches across different
  // workspace.
  string workspace = 2;
}