Build Event Protocol

The Build Event Protocol (BEP) allows third-party programs to gain insight into a Bazel invocation. For example, you could use the BEP to gather information for an IDE plugin or a dashboard that displays build results.

The protocol is a set of protocol buffer messages with some semantics defined on top of it. It includes information about build and test results, build progress, the build configuration and much more. The BEP is intended to be consumed programmatically and makes parsing Bazel’s command line output a thing of the past.

The Build Event Protocol represents information about a build as events. A build event is a protocol buffer message consisting of a build event identifier, a set of child event identifiers, and a payload.

  • Build Event Identifier: Depending on the kind of build event, it might be an opaque string or structured information revealing more about the build event. A build event identifier is unique within a build.

  • Children: A build event may announce other build events, by including their build event identifiers in its children field. For example, the PatternExpanded build event announces the targets it expands to as children. The protocol guarantees that all events, except for the first event, are announced by a previous event.

  • Payload: The payload contains structured information about a build event, encoded as a protocol buffer message specific to that event. Note, that the payload might not be the expected type, but could be an Aborted message e.g. if the build aborted prematurely.

Build event graph

All build events form a directed acyclic graph through their parent and child relationship. Every build event except for the initial build event has one or more parent events. Please note that not all parent events of a child event must 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 event. All other events are its descendants.
  2. Immediate children of the BuildStarted event contain metadata about the command.
  3. Events containing data produced by the command, such as files built and test results, appear before the BuildFinished event.
  4. The 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

To consume the BEP in a binary format:

  1. Have Bazel serialize the protocol buffer messages to a file by specifying the option --build_event_binary_file=/path/to/file. The file will contain serialized protocol buffer messages with each message being length delimited. Each message is prefixed with its length encoded as a variable length integer. This format can be read using the protocol buffer library’s parseDelimitedFrom(InputStream) method.

  2. Then, write a program that extracts the relevant information from the serialized protocol buffer message.

Consume in text or JSON formats

The following Bazel command line flags will output the BEP in human-readable formats, such as text and JSON:

--build_event_text_file
--build_event_json_file

Build Event Service

The Build Event Service Protocol is a generic gRPC service for publishing build events. The Build Event 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. 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.

Build Event Service flags

Bazel has several flags related to the Build Event Service protocol, including:

  • --bes_backend
  • --[no]bes_best_effort
  • --[no]bes_lifecycle_events
  • --bes_results_url
  • --bes_timeout
  • --project_id

For a description of each of these flags, see the Command-Line Reference.

Authentication and security

Bazel’s Build Event Service implementation also supports authentication and TLS. These settings can be controlled using the below flags. Please note that these flags are also used for Bazel’s Remote Execution. This implies that the Build Event Service and Remote Execution Endpoints need to share the same authentication and TLS infrastructure.

  • --[no]google_default_credentials
  • --google_credentials
  • --google_auth_scopes
  • --tls_certificate
  • --[no]tls_enabled

For a description of each of these flags, see the Command-Line Reference.

Build Event Service and remote caching

The BEP typically contains many references to log files (test.log, test.xml, etc. ) stored on the machine where Bazel is running. A remote BES server typically can’t access these files as they are on different machines. A way to work around this issue is to use Bazel with remote caching. Bazel will upload all output files to the remote cache (including files referenced in the BEP) and the BES server can then fetch the referenced files from the cache.

See GitHub issue 3689 for more details.