Build Event Protocol Glossary
Each BEP event type has its own semantics, minimally documented in build_event_stream.proto. The following glossary describes each event type.
Aborted
Unlike other events, Aborted does not have a corresponding ID type, because
the Aborted event replaces events of other types. This event indicates that
the build terminated early and the event ID it appears under was not produced
normally. Aborted contains an enum and human-friendly description to explain
why the build did not complete.
For example, if a build is evaluating a target when the user interrupts Bazel, BEP contains an event like the following:
{
"id": {
"targetCompleted": {
"label": "//:foo",
"configuration": {
"id": "544e39a7f0abdb3efdd29d675a48bc6a"
}
}
},
"aborted": {
"reason": "USER_INTERRUPTED"
}
}
ActionExecuted
Provides details about the execution of a specific
Action in a build. By default, this event is
included in the BEP only for failed actions, to support identifying the root cause
of build failures. Users may set the --build_event_publish_all_actions flag
to include all ActionExecuted events.
BuildFinished
A single BuildFinished event is sent after the command is complete and
includes the exit code for the command. This event provides authoritative
success/failure information.
BuildMetadata
Contains the parsed contents of the --build_metadata flag. This event exists
to support Bazel integration with other tooling by plumbing external data (e.g.
identifiers).
BuildMetrics
A single BuildMetrics event is sent at the end of every command and includes
counters/gauges useful for quantifying the build tool’s behavior during the
command. These metrics indicate work actually done and does not count cached
work that is reused.
Note that memory_metrics may not be populated if there was no Java garbage
collection during the command’s execution. Users may set the
--memory_profile=/dev/null option which forces the garbage collector to run at
the end of the command to populate memory_metrics.
{
"id": {
"buildMetrics": {}
},
"buildMetrics": {
"actionSummary": {
"actionsExecuted": "1"
},
"memoryMetrics": {},
"targetMetrics": {
"targetsLoaded": "9",
"targetsConfigured": "19"
},
"packageMetrics": {
"packagesLoaded": "5"
},
"timingMetrics": {
"cpuTimeInMs": "1590",
"wallTimeInMs": "359"
}
}
}
BuildStarted
The first event in a BEP stream, BuildStarted includes metadata describing the
command before any meaningful work begins.
BuildToolLogs
A single BuildToolLogs event is sent at the end of a command, including URIs
of files generated by the build tool that may aid in understanding or debugging
build tool behavior. Some information may be included inline.
{
"id": {
"buildToolLogs": {}
},
"lastMessage": true,
"buildToolLogs": {
"log": [
{
"name": "elapsed time",
"contents": "MC4xMjEwMDA="
},
{
"name": "process stats",
"contents": "MSBwcm9jZXNzOiAxIGludGVybmFsLg=="
},
{
"name": "command.profile.gz",
"uri": "file:///tmp/.cache/bazel/_bazel_foo/cde87985ad0bfef34eacae575224b8d1/command.profile.gz"
}
]
}
}
CommandLine
The BEP contains multiple CommandLine events containing representations of all
command-line arguments (including options and uninterpreted arguments).
Each CommandLine event has a label in its StructuredCommandLineId that
indicates which representation it conveys; three such events appear in the BEP:
"original": Reconstructed commandline as Bazel received it from the Bazel client, without startup options sourced from .rc files."canonical": The effective commandline with .rc files expanded and invocation policy applied."tool": Populated from the--experimental_tool_command_lineoption. This is useful to convey the command-line of a tool wrapping Bazel through the BEP. This could be a base64-encodedCommandLinebinary protocol buffer messsage which is used directly, or a string which is parsed but not interpreted (as the tool’s options may differ from Bazel’s).
Configuration
A Configuration event is sent for every configuration
used in the top-level targets in a build. At least one configuration event is
always be present. The id is reused by the TargetConfigured and
TargetComplete event IDs and is necessary to disambiguate those events in
multi-configuration builds.
{
"id": {
"configuration": {
"id": "a5d130b0966b4a9ca2d32725aa5baf40e215bcfc4d5cdcdc60f5cc5b4918903b"
}
},
"configuration": {
"mnemonic": "k8-fastbuild",
"platformName": "k8",
"cpu": "k8",
"makeVariable": {
"COMPILATION_MODE": "fastbuild",
"TARGET_CPU": "k8",
"GENDIR": "bazel-out/k8-fastbuild/bin",
"BINDIR": "bazel-out/k8-fastbuild/bin"
}
}
}
ConvenienceSymlinksIdentified
Experimental. If the --experimental_convenience_symlinks_bep_event
option is set, a single ConvenienceSymlinksIdentified event is produced by
build commands to indicate how symlinks in the workspace should be managed.
This enables building tools that invoke Bazel remotely then arrange the local
workspace as if Bazel had been run locally.
{
"id": {
"convenienceSymlinksIdentified":{}
},
"convenienceSymlinksIdentified": {
"convenienceSymlinks": [
{
"path": "bazel-bin",
"action": "CREATE",
"target": "execroot/google3/bazel-out/k8-fastbuild/bin"
},
{
"path": "bazel-genfiles",
"action": "CREATE",
"target": "execroot/google3/bazel-out/k8-fastbuild/genfiles"
},
{
"path": "bazel-out",
"action": "CREATE",
"target": "execroot/google3/bazel-out"
}
]
}
}
Fetch
Indicates that a Fetch operation occurred as a part of the command execution. Unlike other events, if a cached fetch result is re-used, this event does not appear in the BEP stream.
NamedSetOfFiles
NamedSetOfFiles events report a structure matching a
depset of files produced during command evaluation.
Transitively included depsets are identified by NamedSetOfFilesId.
For more information on interpreting a stream’s NamedSetOfFiles events, see the
BEP examples page.
OptionsParsed
A single OptionsParsed event lists all options applied to the command,
separating startup options from command options. It also includes the
InvocationPolicy, if any.
{
"id": {
"optionsParsed": {}
},
"optionsParsed": {
"startupOptions": [
"--max_idle_secs=10800",
"--noshutdown_on_low_sys_mem",
"--connect_timeout_secs=30",
"--output_user_root=/tmp/.cache/bazel/_bazel_foo",
"--output_base=/tmp/.cache/bazel/_bazel_foo/a61fd0fbee3f9d6c1e30d54b68655d35",
"--deep_execroot",
"--expand_configs_in_place",
"--idle_server_tasks",
"--write_command_log",
"--nowatchfs",
"--nofatal_event_bus_exceptions",
"--nowindows_enable_symlinks",
"--noclient_debug",
],
"cmdLine": [
"--enable_platform_specific_config",
"--build_event_json_file=/tmp/bep.json"
],
"explicitCmdLine": [
"--build_event_json_file=/tmp/bep.json"
],
"invocationPolicy": {}
}
}
PatternExpanded
PatternExpanded events indicate the set of all targets that match the patterns
supplied on the commandline. For successful commands, a single event is present
with all patterns in the PatternExpandedId and all targets in the
PatternExpanded event’s children. If the pattern expands to any
test_suites the set of test targets included by the test_suite. For each
pattern that fails to resolve, BEP contains an additional Aborted
event with a PatternExpandedId identifying the pattern.
{
"id": {
"pattern": {
"pattern":["//base:all"]
}
},
"children": [
{"targetConfigured":{"label":"//base:foo"}},
{"targetConfigured":{"label":"//base:foobar"}}
],
"expanded": {
"testSuiteExpansions": {
"suiteLabel": "//base:suite",
"testLabels": "//base:foo_test"
}
}
}
Progress
Progress events contain the standard output and standard error produced by Bazel during command execution. These events are also auto-generated as needed to announce events that have not been announced by a logical “parent” event (in particular, NamedSetOfFiles.)
TargetComplete
For each (target, configuration, aspect) combination that completes the
execution phase, a TargetComplete event is included in BEP. The event contains
the target’s success/failure and the target’s requested output groups.
{
"id": {
"targetCompleted": {
"label": "//examples/py:bep",
"configuration": {
"id": "a5d130b0966b4a9ca2d32725aa5baf40e215bcfc4d5cdcdc60f5cc5b4918903b"
}
}
},
"completed": {
"success": true,
"outputGroup": [
{
"name": "default",
"fileSets": [
{
"id": "0"
}
]
}
]
}
}
TargetConfigured
For each Target that completes the analysis phase, a TargetConfigured event is
included in BEP. This is the authoritative source for a target’s “rule kind”
attribute. The configuration(s) applied to the target appear in the announced
children of the event.
For example, building with the --experimental_multi_cpu options may produce
the following TargetConfigured event for a single target with two
configurations:
{
"id": {
"targetConfigured": {
"label": "//starlark_configurations/multi_arch_binary:foo"
}
},
"children": [
{
"targetCompleted": {
"label": "//starlark_configurations/multi_arch_binary:foo",
"configuration": {
"id": "c62b30c8ab7b9fc51a05848af9276529842a11a7655c71327ade26d7c894c818"
}
}
},
{
"targetCompleted": {
"label": "//starlark_configurations/multi_arch_binary:foo",
"configuration": {
"id": "eae0379b65abce68d54e0924c0ebcbf3d3df26c6e84ef7b2be51e8dc5b513c99"
}
}
}
],
"configured": {
"targetKind": "foo_binary rule"
}
}
TargetSummary
For each (target, configuration) pair that is executed, a TargetSummary
event is included with an aggregate success result encompassing the configured
target’s execution and all aspects applied to that configured target.
TestResult
If testing is requested, a TestResult event is sent for each test attempt,
shard, and run per test. This allows BEP consumers to identify precisely which
test actions failed their tests and identify the test outputs (e.g. logs,
test.xml files) for each test action.
TestSummary
If testing is requested, a TestSummary event is sent for each test (target,
configuration), containing information necessary to interpret the test’s
results. The number of attempts, shards and runs per test are included to enable
BEP consumers to differentiate artifacts across these dimensions. The attempts
and runs per test are considered while producing the aggregate TestStatus to
differentiate FLAKY tests from FAILED tests.
UnstructuredCommandLine
Unlike CommandLine, this event carries the unparsed commandline
flags in string form as encountered by the build tool after expanding all
.bazelrc files and
considering the --config flag.
The UnstructuredCommandLine event may be relied upon to precisely reproduce a
given command execution.
WorkspaceConfig
A single WorkspaceConfig event contains configuration information regarding the
workspace, such as the execution root.
WorkspaceStatus
A single WorkspaceStatus event contains the result of the workspace status
command.