Update BEP docs to clarify graph shape, include diagram for NestedSet…

…OfFiles.

Also clarifies how to set the --bes_backend flag correctly.

PiperOrigin-RevId: 373395007

site/docs/bep-examples.md

@@ -14,14 +14,9 @@ Consider a simple Bazel workspace that consists of two empty shell scripts
 `foo.sh` and `foo_test.sh` and the following BUILD file:
 
 ```bash
-sh_binary(
-    name = "foo",
-    srcs = ["foo.sh"],
-)
-
 sh_library(
     name = "foo_lib",
-    data = [":foo"],
+    srcs = ["foo.sh"],
 )
 
 sh_test(
@@ -53,11 +48,11 @@ build was invoked through the `bazel test` command and announces child events:
 The first three events provide information about how Bazel was invoked.
 
 The `PatternExpanded` build event provides insight
-into which specific targets the `...` pattern expanded to: `//:foo`,
-`//:foo_lib` and `//:foo_test`. It does so by declaring three `TargetConfigured`
-events as children. Note that the `TargetConfigured` event declares the
-`Configuration` event as a child event, even though `Configuration` has been
-posted before the `TargetConfigured` event.
+into which specific targets the `...` pattern expanded to:
+`//foo:foo_lib` and `//foo:foo_test`. It does so by declaring two
+`TargetConfigured` events as children. Note that the `TargetConfigured` event
+declares the `Configuration` event as a child event, even though `Configuration`
+has been posted before the `TargetConfigured` event.
 
 Besides the parent and child relationship, events may also refer to each other
 using their build event identifiers. For example, in the above graph the
@@ -74,10 +69,10 @@ the number of files. A `NamedSetOfFiles` event may also not have all its files
 embedded, but instead refer to other `NamedSetOfFiles` events through their
 build event identifiers.
 
-Below is an instance of the `TargetComplete` event for the `//:foo_lib` target
-from the above graph, printed in protocol buffer’s JSON representation. The
-build event identifier contains the target as an opaque string and refers to the
-`Configuration` event using its build event identifier. The event does not
+Below is an instance of the `TargetComplete` event for the `//foo:foo_lib`
+target from the above graph, printed in protocol buffer’s JSON representation.
+The build event identifier contains the target as an opaque string and refers to
+the `Configuration` event using its build event identifier. The event does not
 announce any child events. The payload contains information about whether the
 target was built successfully, the set of output files, and the kind of target
 built.
@@ -86,7 +81,7 @@ built.
 {
   "id": {
     "targetCompleted": {
-      "label": "//:foo_lib",
+      "label": "//foo:foo_lib",
       "configuration": {
         "id": "544e39a7f0abdb3efdd29d675a48bc6a"
       }
@@ -124,7 +119,7 @@ the BEP:
 {
   "id": {
     "targetCompleted": {
-      "label": "//:foo_lib",
+      "label": "//foo:foo_lib",
       "configuration": {
         "id": "544e39a7f0abdb3efdd29d675a48bc6a"
       },
@@ -158,6 +153,8 @@ Consumers must take care to avoid quadratic algorithms when processing
 such events, requiring hundreds of millions operations in a traversal with
 quadratic complexity.
 
+![namedsetoffiles-bep-graph](/assets/namedsetoffiles-bep-graph.png)
+
 A `NamedSetOfFiles` event always appears in the BEP stream *before* a
 `TargetComplete` or `NamedSetOfFiles` event that references it. This is the
 inverse of the "parent-child" event relationship, where all but the first event

site/docs/build-event-protocol.md

@@ -52,6 +52,20 @@ necessarily be posted before it. When a build is complete (succeeded or failed)
 all announced events will have been posted. In case of a Bazel crash or a failed
 network transport, some announced build events may never be posted.
 
+The event graph's structure reflects the lifecycle of a command. Every BEP
+graph has the following characteristic shape:
+
+1. The root event is always a [`BuildStarted`](bep-glossary.md#buildstarted)
+   event. All other events are its descendants.
+1. Immediate children of the BuildStarted event contain metadata about the
+   command.
+1. Events containing data produced by the command, such as files built and test
+   results, appear before the [`BuildFinished`](bep-glossary.md#buildfinished)
+   event.
+1. The [`BuildFinished`](bep-glossary.md#buildfinished) event *may* be followed
+   by events containing summary information about the build (for example, metric
+   or profiling data).
+
 ## Consuming Build Event Protocol
 
 ### Consume in binary format
@@ -88,8 +102,9 @@ Protocol is a generic [gRPC](https://www.grpc.io) service for publishing build e
 Service protocol is independent of the BEP and treats BEP events as opaque bytes.
 Bazel ships with a gRPC client implementation of the Build Event Service protocol that
 publishes Build Event Protocol events. One can specify the endpoint to send the
-events to using the `--bes_backend=HOST:PORT` flag. Bazel’s implementation also
-supports TLS which can be enabled by specifying the `--tls_enabled` flag.
+events to using the `--bes_backend=HOST:PORT` flag. If your backend uses gRPC,
+you must prefix the address with the appropriate scheme: `grpc://` for plaintext
+gRPC and `grpcs://` for gRPC with TLS enabled.
 
 There is currently an experimental open source implementation of the [Build
 Event Service](https://github.com/buildbarn/bb-event-service/) in Go as part of
@@ -140,4 +155,3 @@ from the cache.
 See [GitHub issue 3689](https://github.com/bazelbuild/bazel/issues/3689) for
 more details.
 
-