| --- |
| layout: documentation |
| title: Build Event Protocol Glossary |
| --- |
| |
| # Build Event Protocol Glossary |
| |
| |
| Each BEP event type has its own semantics, minimally documented in |
| [build\_event\_stream.proto](https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/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: |
| |
| <p> |
| <button class="btn btn-primary" type="button" data-toggle="collapse" |
| data-target="#collapseAbortedJson" aria-expanded="false" |
| aria-controls="collapseAbortedJson"> |
| Show/Hide BEP JSON |
| </button> |
| </p> |
| |
| ```json |
| { |
| "id": { |
| "targetCompleted": { |
| "label": "//:foo", |
| "configuration": { |
| "id": "544e39a7f0abdb3efdd29d675a48bc6a" |
| } |
| } |
| }, |
| "aborted": { |
| "reason": "USER_INTERRUPTED" |
| } |
| } |
| ``` |
| {: .collapse #collapseAbortedJson} |
| |
| ## ActionExecuted |
| |
| Provides details about the execution of a specific |
| [Action](https://docs.bazel.build/skylark/lib/actions.html) 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`. |
| |
| <p> |
| <button class="btn btn-primary" type="button" data-toggle="collapse" |
| data-target="#collapseBuildMetricsJson" aria-expanded="false" |
| aria-controls="collapseBuildMetricsJson"> |
| Show/Hide BEP JSON |
| </button> |
| </p> |
| |
| ```json |
| { |
| "id": { |
| "buildMetrics": {} |
| }, |
| "buildMetrics": { |
| "actionSummary": { |
| "actionsExecuted": "1" |
| }, |
| "memoryMetrics": {}, |
| "targetMetrics": { |
| "targetsLoaded": "9", |
| "targetsConfigured": "19" |
| }, |
| "packageMetrics": { |
| "packagesLoaded": "5" |
| }, |
| "timingMetrics": { |
| "cpuTimeInMs": "1590", |
| "wallTimeInMs": "359" |
| } |
| } |
| } |
| ``` |
| {: .collapse #collapseBuildMetricsJson} |
| |
| ## 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. |
| |
| <p> |
| <button class="btn btn-primary" type="button" data-toggle="collapse" |
| data-target="#collapseBuildToolLogsJson" aria-expanded="false" |
| aria-controls="collapseBuildToolLogsJson"> |
| Show/Hide BEP JSON |
| </button> |
| </p> |
| |
| ```json |
| { |
| "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" |
| } |
| ] |
| } |
| } |
| ``` |
| {: .collapse #collapseBuildToolLogsJson} |
| |
| ## 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_line` option. This |
| is useful to convey the command-line of a tool wrapping Bazel through the BEP. |
| This could be a base64-encoded `CommandLine` binary 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`](https://docs.bazel.build/skylark/config.html) |
| 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. |
| |
| <p> |
| <button class="btn btn-primary" type="button" data-toggle="collapse" |
| data-target="#collapseConfigurationJson" aria-expanded="false" |
| aria-controls="collapseConfigurationJson"> |
| Show/Hide BEP JSON |
| </button> |
| </p> |
| |
| ```json |
| { |
| "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" |
| } |
| } |
| } |
| ``` |
| {: .collapse #collapseConfigurationJson} |
| |
| ## 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. |
| |
| <p> |
| <button class="btn btn-primary" type="button" data-toggle="collapse" |
| data-target="#collapseConvenienceSymlinksIdentifiedJson" |
| aria-expanded="false" |
| aria-controls="collapseConvenienceSymlinksIdentifiedJson"> |
| Show/Hide BEP JSON |
| </button> |
| </p> |
| |
| ```json |
| { |
| "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" |
| } |
| ] |
| } |
| } |
| ``` |
| {: .collapse #collapseConvenienceSymlinksIdentifiedJson} |
| |
| ## 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`](https://docs.bazel.build/skylark/depsets.html) 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](bep-examples.html#consuming-namedsetoffiles). |
| |
| ## OptionsParsed |
| |
| A single `OptionsParsed` event lists all options applied to the command, |
| separating startup options from command options. It also includes the |
| [InvocationPolicy](https://docs.bazel.build/command-line-reference.html#flag--invocation_policy), if any. |
| |
| <p> |
| <button class="btn btn-primary" type="button" data-toggle="collapse" |
| data-target="#collapseOptionsParsedJson" aria-expanded="false" |
| aria-controls="collapseOptionsParsedJson"> |
| Show/Hide BEP JSON |
| </button> |
| </p> |
| |
| ```json |
| { |
| "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": {} |
| } |
| } |
| ``` |
| {: .collapse #collapseOptionsParsedJson} |
| |
| ## 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_suite`s the set of test targets included by the `test_suite`. For each |
| pattern that fails to resolve, BEP contains an additional [`Aborted`](#aborted) |
| event with a `PatternExpandedId` identifying the pattern. |
| |
| <p> |
| <button class="btn btn-primary" type="button" data-toggle="collapse" |
| data-target="#collapsePatternExpandedJson" aria-expanded="false" |
| aria-controls="collapsePatternExpandedJson"> |
| Show/Hide BEP JSON |
| </button> |
| </p> |
| |
| ```json |
| { |
| "id": { |
| "pattern": { |
| "pattern":["//base:all"] |
| } |
| }, |
| "children": [ |
| {"targetConfigured":{"label":"//base:foo"}}, |
| {"targetConfigured":{"label":"//base:foobar"}} |
| ], |
| "expanded": { |
| "testSuiteExpansions": { |
| "suiteLabel": "//base:suite", |
| "testLabels": "//base:foo_test" |
| } |
| } |
| } |
| ``` |
| {: .collapse #collapsePatternExpandedJson} |
| |
| ## 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](#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. |
| |
| <p> |
| <button class="btn btn-primary" type="button" data-toggle="collapse" |
| data-target="#collapseTargetCompleteJson" aria-expanded="false" |
| aria-controls="collapseTargetCompleteJson"> |
| Show/Hide BEP JSON |
| </button> |
| </p> |
| |
| ```json |
| { |
| "id": { |
| "targetCompleted": { |
| "label": "//examples/py:bep", |
| "configuration": { |
| "id": "a5d130b0966b4a9ca2d32725aa5baf40e215bcfc4d5cdcdc60f5cc5b4918903b" |
| } |
| } |
| }, |
| "completed": { |
| "success": true, |
| "outputGroup": [ |
| { |
| "name": "default", |
| "fileSets": [ |
| { |
| "id": "0" |
| } |
| ] |
| } |
| ] |
| } |
| } |
| ``` |
| {: .collapse #collapseTargetCompleteJson} |
| |
| ## 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: |
| |
| <p> |
| <button class="btn btn-primary" type="button" data-toggle="collapse" |
| data-target="#collapseTargetConfiguredJson" aria-expanded="false" |
| aria-controls="collapseTargetConfiguredJson"> |
| Show/Hide BEP JSON |
| </button> |
| </p> |
| |
| ```json |
| { |
| "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" |
| } |
| } |
| ``` |
| {: .collapse #collapseTargetConfiguredJson} |
| |
| ## 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](#commandline), this event carries the unparsed commandline |
| flags in string form as encountered by the build tool after expanding all |
| [`.bazelrc`](guide.html#bazelrc-the-bazel-configuration-file) 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](user-manual.html#workspace_status). |