Clarify the role of the WorkResponse.output field.
The documentation suggests that the stdout/stderr of a work unit may be sent to the stderr of the worker process, but this will fail to ascribe the output to a particular action; instead it will be collected in a per-worker log file [1][2]. In contrast, the WorkResponse.output field is copied to the action stderr [3].
[1] https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/worker/SingleplexWorker.java;l=111;drc=290315e048b94c351f2fa23bfef2a164b6f78268
[2] https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/worker/WorkerMultiplexer.java;l=203;drc=0b280ac442aa51c7cca1c311658dbd1a6346dff5
[3] https://cs.opensource.google/bazel/bazel/+/master:src/main/java/com/google/devtools/build/lib/worker/WorkerSpawnRunner.java;l=214;drc=e3aae6ca8bba30561b01b2727bcffca8b74638cc
PiperOrigin-RevId: 649380094
Change-Id: I22209f14cfe69660aeaa2a8f53b8086df8bd1e30
diff --git a/site/en/remote/creating.md b/site/en/remote/creating.md
index 9469198..dddf830 100644
--- a/site/en/remote/creating.md
+++ b/site/en/remote/creating.md
@@ -70,11 +70,12 @@
### Work responses {:#work-responses}
A `WorkResponse` contains a request id, a zero or nonzero exit code, and an
-output string that describes any errors encountered in processing or executing
-the request. The `output` field contains a short description; complete logs may
-be written to the worker's `stderr`. Because workers may only write
-`WorkResponses` to `stdout`, it's common for the worker to redirect the `stdout`
-of any tools it uses to `stderr`.
+output message describing any errors encountered in processing or executing
+the request. A worker should capture the `stdout` and `stderr` of any tool it
+calls and report them through the `WorkResponse`. Writing it to the `stdout` of
+the worker process is unsafe, as it will interfere with the worker protocol.
+Writing it to the `stderr` of the worker process is safe, but the result is
+collected in a per-worker log file instead of ascribed to individual actions.
```json
{
diff --git a/src/main/protobuf/worker_protocol.proto b/src/main/protobuf/worker_protocol.proto
index 4bca448..ae17121 100644
--- a/src/main/protobuf/worker_protocol.proto
+++ b/src/main/protobuf/worker_protocol.proto
@@ -77,9 +77,11 @@
message WorkResponse {
int32 exit_code = 1;
- // This is printed to the user after the WorkResponse has been received and is
- // supposed to contain compiler warnings / errors etc. - thus we'll use a
- // string type here, which gives us UTF-8 encoding.
+ // Output message for this work unit.
+ // This is akin to the combined stdout/stderr if the work unit were executed
+ // as a standalone process. Output pertaining to a work unit should be
+ // reported here instead of through the stdout/stderr of the worker process.
+ // Assumed to be UTF-8 encoded.
string output = 2;
// This field must be set to the same request_id as the WorkRequest it is a
