Project: /_project.yaml Book: /_book.yaml

Build Event Protocol Glossary

{% include “_buttons.html” %}

Each BEP event type has its own semantics, minimally documented in build_event_stream.proto{: .external}. The following glossary describes each event type.

Aborted {:#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 {:#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 {:#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 {:#buildmetadata}

Contains the parsed contents of the --build_metadata flag. This event exists to support Bazel integration with other tooling by plumbing external data (such as identifiers).

BuildMetrics {:#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 {:#buildstarted}

The first event in a BEP stream, BuildStarted includes metadata describing the command before any meaningful work begins.

BuildToolLogs {:#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 {:#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 message which is used directly, or a string which is parsed but not interpreted (as the tool‘s options may differ from Bazel’s).

Configuration {:#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 {:#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 {:#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}

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 {:#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}

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}

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 {:#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 {:#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 {:#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 {:#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 (such as logs, test.xml files) for each test action.

TestSummary {:#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 {:#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 {:#workspaceconfig}

A single WorkspaceConfig event contains configuration information regarding the workspace, such as the execution root.

WorkspaceStatus {:#workspacestatus}

A single WorkspaceStatus event contains the result of the workspace status command.