> ## Documentation Index
> Fetch the complete documentation index at: https://bazel.build/llms.txt
> Use this file to discover all available pages before exploring further.
# Build Event Protocol
The [Build Event Protocol](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto)
(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](https://developers.google.com/protocol-buffers/) 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](https://github.com/bazelbuild/bazel/blob/7.1.0/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto#L131-L140)
or [structured information](https://github.com/bazelbuild/bazel/blob/7.1.0/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto#L194-L205)
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](https://github.com/bazelbuild/bazel/blob/7.1.0/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream.proto#L1276).
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
if the build aborted prematurely.
Build event graph
All build events form a directed acyclic graph (DAG) through their parent and child
relationships. Every build event except for the initial `BuildStarted` event is announced
by one or more earlier parent events.
#### Announcement contract
The protocol requires that every event in the stream (except `BuildStarted`) is announced in the `children` list of an earlier event:
* **Static parents:** High-level lifecycle events announce their natural children. For example, `BuildStarted` announces `PatternExpanded` and `BuildFinished`, and `PatternExpanded` announces `TargetConfigured` for each matching target.
* **Dynamic chaining via Progress:** Events discovered dynamically during evaluation that have no natural static parent—such as `NamedSetOfFiles`, `Configuration`, `WorkspaceConfig`, and `Fetch`—are announced on the fly by intervening `Progress` events before they are posted.
* **Completion invariant:** A build is considered complete if and only if all announced children have been posted or accounted for with an [`Aborted`](/remote/bep-glossary#aborted) event.
#### Announcement vs. delivery ordering
Being announced in `children` advertises that an event will eventually occur, but it does *not* imply delivery sequence:
* Bazel posts events concurrently as actions complete across worker threads.
* Some events (such as `TargetComplete`, `TestResult`, and `TestSummary`) specify order constraints (`postedAfter` in the Bazel implementation). Bazel holds back delivering these events until their prerequisite events have been posted.
* For test executions, `TargetComplete` announces initial test attempts (`TestResult`), while each retry attempt is announced by the attempt that immediately preceded it.
#### Lifecycle stages
The event graph reflects the phases of a Bazel invocation:
1. **Invocation Start:** The root [`BuildStarted`](/remote/bep-glossary#buildstarted) event is published first. It announces command metadata (`OptionsParsed`, `CommandLine`, `WorkspaceStatus`), target pattern expansion (`PatternExpanded`), and build completion (`BuildFinished`).
2. **Analysis & Configuration:** `PatternExpanded` announces `TargetConfigured` events for parsed targets. Intervening `Progress` events chain in build configurations (`Configuration`).
3. **Execution:** Each `TargetConfigured` event announces its corresponding [`TargetComplete`](/remote/bep-glossary#targetcomplete) event. `TargetComplete` references output file sets (`NamedSetOfFiles`, which are dynamically announced via intervening `Progress` events) and announces target-level summaries ([`TargetSummary`](/remote/bep-glossary#targetsummary)) as well as test events ([`TestResult`](/remote/bep-glossary#testresult), [`TestSummary`](/remote/bep-glossary#testsummary)) for test targets.
4. **Completion & Tool Logs:** The [`BuildFinished`](/remote/bep-glossary#buildfinished) event is published after command evaluation finishes, providing the authoritative exit code. It announces post-build events such as [`BuildMetrics`](/remote/bep-glossary#buildmetrics), [`BuildToolLogs`](/remote/bep-glossary#buildtoollogs), and, for `bazel run` without `--script_path`, [`ExecRequestConstructed`](/remote/bep-glossary#execrequestconstructed). These may arrive in any order; the final event of the stream has `last_message` set.
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)`](https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/AbstractParser#parseDelimitedFrom-java.io.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](https://github.com/googleapis/googleapis/blob/master/google/devtools/build/v1/publish_build_event.proto)
Protocol is a generic [gRPC](https://www.grpc.io) 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_lifecycle_events`
* `--bes_results_url`
* `--bes_timeout`
* `--bes_instance_name`
For a description of each of these flags, see the
[Command-Line Reference](/reference/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](/reference/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](/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](https://github.com/bazelbuild/bazel/issues/3689) for
more details.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.