Update https://bazel.build/remote/cache-remote in light of recent improvements.
* Recommend the compact format over the binary and JSON formats.
* Note that `//src/tools/execlog:parser` can be used with any format.
* Note that `//src/tools/execlog:converter` can be used to convert between formats.
PiperOrigin-RevId: 680941049
Change-Id: I81caf27a4ff6aef0ea97667df5ccbba1c3f10d58
diff --git a/site/en/remote/cache-remote.md b/site/en/remote/cache-remote.md
index b3fa4bb..06cb579 100644
--- a/site/en/remote/cache-remote.md
+++ b/site/en/remote/cache-remote.md
@@ -65,7 +65,7 @@
```posix-terminal
bazel clean
- bazel {{ '<var>' }}--optional-flags{{ '</var>' }} build //{{ '<var>' }}your:target{{ '</var>' }} --execution_log_binary_file=/tmp/exec1.log
+ bazel {{ '<var>' }}--optional-flags{{ '</var>' }} build //{{ '<var>' }}your:target{{ '</var>' }} --execution_log_compact_file=/tmp/exec1.log
```
b. [Compare the execution logs](#compare-logs) between the
@@ -122,7 +122,7 @@
```posix-terminal
bazel clean
- bazel ... build ... --execution_log_binary_file=/tmp/exec1.log
+ bazel ... build ... --execution_log_compact_file=/tmp/exec1.log
```
3. Run the build on the second machine, ensuring the modification from step 1
@@ -131,7 +131,7 @@
```posix-terminal
bazel clean
- bazel ... build ... --execution_log_binary_file=/tmp/exec2.log
+ bazel ... build ... --execution_log_compact_file=/tmp/exec2.log
```
4. [Compare the execution logs](#compare-logs-the-execution-logs) for the two
@@ -141,15 +141,17 @@
## Comparing the execution logs {:#compare-logs}
-Execution logs contain records of all actions executed during the build. For
-each action there is a
-[SpawnExec](https://github.com/bazelbuild/bazel/blob/42389d9468a954f3793a19f8e026b022b39aefca/src/main/protobuf/spawn.proto#L67){: .external}
-element containing all of the information from the action key, Thus, if the
-logs are identical then so are the action cache keys.
+The execution log contains records of actions executed during the build.
+Each record describes both the inputs (not only files, but also command line
+arguments, environment variables, etc) and the outputs of the action. Thus,
+examination of the log can reveal why an action was reexecuted.
-If you're using the `--experimental_execution_log_compact_file` flag you
-must first convert to the binary or json format using the
-`//src/tools/execlog:converter` tool.
+The execution log can be produced in one of three formats:
+compact (`--execution_log_compact_file`),
+binary (`--execution_log_binary_file`) or JSON (`--execution_log_json_file`).
+The compact format is recommended, as it produces much smaller files with very
+little runtime overhead. The following instructions work for any format. You
+can also convert between them using the `//src/tools/execlog:converter` tool.
To compare logs for two builds that are not sharing cache hits as expected,
do the following:
@@ -157,19 +159,17 @@
1. Get the execution logs from each build and store them as `/tmp/exec1.log` and
`/tmp/exec2.log`.
-2. Download the Bazel source code and navigate to the Bazel folder by using
- the command below. You need the source code to parse the
- execution logs with the
- [execlog parser](https://source.bazel.build/bazel/+/master:src/tools/execlog/).
+2. Download the Bazel source code and build the `//src/tools/execlog:parser`
+ tool:
- git clone https://github.com/bazelbuild/bazel.git
- cd bazel
+ git clone https://github.com/bazelbuild/bazel.git
+ cd bazel
+ bazel build //src/tools/execlog:parser
-3. Use the execution log parser to convert the logs to text. The following
- invocation also sorts the actions in the second log to match the action order
- in the first log for ease of comparison.
+3. Use the `//src/tools/execlog:parser` tool to convert the logs into a
+ human-readable text format. In this format, the actions in the second log are
+ sorted to match the order in the first log, making a comparison easier.
- bazel build src/tools/execlog:parser
bazel-bin/src/tools/execlog/parser \
--log_path=/tmp/exec1.log \
--log_path=/tmp/exec2.log \
