BazelCon 2024 报名现已开放！

此页面由 Cloud Translation API 翻译。

Build Event Protocol 术语表

报告问题查看源代码每夜 build · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

每种 BEP 事件类型都有自己的语义，build_event_stream.proto 中对此进行了最基本的说明。以下术语表介绍了每种事件类型。

已中止

与其他事件不同，Aborted 没有对应的 ID 类型，因为 Aborted 事件会替换其他类型的事件。此事件表示 build 过早终止，并且其下显示的事件 ID 未正常生成。Aborted 包含一个枚举和直观易懂的说明，用于说明 build 未完成的原因。

例如，如果用户在 build 正在评估目标时中断 Bazel，BEP 中会包含如下事件：

{
  "id": {
    "targetCompleted": {
      "label": "//:foo",
      "configuration": {
        "id": "544e39a7f0abdb3efdd29d675a48bc6a"
      }
    }
  },
  "aborted": {
    "reason": "USER_INTERRUPTED"
  }
}

ActionExecuted

提供有关 build 中特定操作执行的详细信息。默认情况下，只有失败的操作才会在 BEP 中包含此事件，以便确定构建失败的根本原因。用户可以设置 --build_event_publish_all_actions 标志以包含所有 ActionExecuted 事件。

BuildFinished

命令完成后，系统会发送一个 BuildFinished 事件，其中包含命令的退出代码。此事件提供权威性的成功/失败信息。

BuildMetadata

包含 --build_metadata 标志的解析内容。此事件旨在通过管道传输外部数据（例如标识符），支持 Bazel 与其他工具集成。

BuildMetrics

系统会在每条命令结束时发送一个 BuildMetrics 事件，其中包含有助于量化命令期间构建工具行为的计数器/仪表板。这些指标表示实际完成的工作，不计入被重复使用的缓存工作。

请注意，如果命令执行期间没有进行 Java 垃圾回收，则可能不会填充 memory_metrics。用户可以设置 --memory_profile=/dev/null 选项，以强制在命令结束时运行垃圾回收器以填充 memory_metrics。

{
  "id": {
    "buildMetrics": {}
  },
  "buildMetrics": {
    "actionSummary": {
      "actionsExecuted": "1"
    },
    "memoryMetrics": {},
    "targetMetrics": {
      "targetsLoaded": "9",
      "targetsConfigured": "19"
    },
    "packageMetrics": {
      "packagesLoaded": "5"
    },
    "timingMetrics": {
      "cpuTimeInMs": "1590",
      "wallTimeInMs": "359"
    }
  }
}

BuildStarted

BEP 流中的第一个事件 BuildStarted 包含在开始任何有意义的工作之前描述该命令的元数据。

BuildToolLogs

系统会在命令结束时发送一个 BuildToolLogs 事件，其中包含构建工具生成的文件的 URI，这些 URI 可能有助于了解或调试构建工具行为。部分信息可能会内嵌在其中。

{
  "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

BEP 包含多个 CommandLine 事件，其中包含所有命令行参数（包括选项和未解析参数）的表示法。每个 CommandLine 事件的 StructuredCommandLineId 中都有一个标签，用于指明它传达的是哪种表示法；BEP 中显示了三种此类事件：

"original"：重构了 Bazel 从 Bazel 客户端收到的命令行，其中不包含来自 .rc 文件的启动选项。
"canonical"：已展开 .rc 文件并应用调用政策的有效命令行。
"tool"：从 --experimental_tool_command_line 选项填充。这对于通过 BEP 传达封装 Bazel 的工具的命令行非常有用。这可以是直接使用的 base64 编码的 CommandLine 二进制协议缓冲区消息，也可以是被解析但未被解读的字符串（因为该工具的选项可能与 Bazel 的选项不同）。

配置

系统会针对 build 中顶级目标中使用的每个 configuration 发送 Configuration 事件。始终存在至少一个配置事件。id 由 TargetConfigured 和 TargetComplete 事件 ID 重复使用，并且对于在多配置 build 中对这些事件进行区分非常必要。

{
  "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_convenience_symlinks_bep_event 选项，build 命令会生成单个 ConvenienceSymlinksIdentified 事件，以指明应如何管理工作区中的符号链接。这样，构建工具就可以远程调用 Bazel，然后将本地工作区整理得像是在本地运行 Bazel 一样。

{
  "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"
      }
    ]
  }
}

抓取

表示在命令执行过程中发生了提取操作。与其他事件不同，如果缓存的提取结果被重复使用，此事件不会显示在 BEP 数据流中。

NamedSetOfFiles

NamedSetOfFiles 事件会报告与命令评估期间生成的文件的 depset 匹配的结构。传递包含的 depset 由 NamedSetOfFilesId 标识。

如需详细了解如何解读数据流的 NamedSetOfFiles 事件，请参阅 BEP 示例页面。

OptionsParsed

单个 OptionsParsed 事件会列出应用于该命令的所有选项，并将启动选项与命令选项分开。它还包含 InvocationPolicy（如果有）。

{
  "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 事件表示与命令行中提供的模式匹配的所有目标的集合。对于成功的命令，系统会显示一个事件，其中包含 PatternExpandedId 中的所有模式以及 PatternExpanded 事件的子项中的所有目标。如果模式扩展到任何 test_suite，则为 test_suite 包含的一组测试目标。对于每个无法解析的模式，BEP 都会包含一个额外的 Aborted 事件，其中包含用于标识该模式的 PatternExpandedId。

{
  "id": {
    "pattern": {
      "pattern":["//base:all"]
    }
  },
  "children": [
    {"targetConfigured":{"label":"//base:foo"}},
    {"targetConfigured":{"label":"//base:foobar"}}
  ],
  "expanded": {
    "testSuiteExpansions": {
      "suiteLabel": "//base:suite",
      "testLabels": "//base:foo_test"
    }
  }
}

进度

进度事件包含 Bazel 在命令执行期间生成的标准输出和标准错误。系统还会根据需要自动生成这些事件，以宣布逻辑“父级”事件（尤其是 NamedSetOfFiles）尚未宣布的事件。

TargetComplete

对于完成执行阶段的每个 (target, configuration, aspect) 组合，BEP 中都会包含一个 TargetComplete 事件。该事件包含目标的成功/失败情况以及目标请求的输出组。

{
  "id": {
    "targetCompleted": {
      "label": "//examples/py:bep",
      "configuration": {
        "id": "a5d130b0966b4a9ca2d32725aa5baf40e215bcfc4d5cdcdc60f5cc5b4918903b"
      }
    }
  },
  "completed": {
    "success": true,
    "outputGroup": [
      {
        "name": "default",
        "fileSets": [
          {
            "id": "0"
          }
        ]
      }
    ]
  }
}

TargetConfigured

对于完成分析阶段的每个目标，BEP 中都会包含一个 TargetConfigured 事件。这是目标的“规则类型”属性的权威来源。应用于目标的配置会显示在事件的已声明子元素中。

例如，使用 --experimental_multi_cpu 选项进行构建时，对于具有两个配置的单个目标，可能会生成以下 TargetConfigured 事件：

{
  "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

对于执行的每个 (target, configuration) 对，系统都会包含一个 TargetSummary 事件，其中包含一个汇总成功结果，该结果涵盖配置的目标的执行以及应用于该配置目标的所有方面。

TestResult

如果请求进行测试，系统会针对每次测试尝试、分片和运行发送 TestResult 事件。这样一来，BEP 使用方就可以准确确定哪些测试操作的测试失败，并确定每个测试操作的测试输出（例如日志、test.xml 文件）。

TestSummary

如果请求进行测试，系统会针对每个测试 (target, configuration) 发送一个 TestSummary 事件，其中包含解读测试结果所需的信息。其中包含每项测试的尝试次数、分片数和运行次数，以便 BEP 使用方能够根据这些维度对工件进行区分。在生成汇总 TestStatus 时，系统会考虑每项测试的尝试次数和运行次数，以便将 FLAKY 测试与 FAILED 测试区分开来。

UnstructuredCommandLine

与 CommandLine 不同，此事件以字符串形式携带未解析的命令行标志，这些标志是构建工具在展开所有 .bazelrc 文件并考虑 --config 标志后遇到的。

您可以依赖 UnstructuredCommandLine 事件来精确重现给定命令的执行。

WorkspaceConfig

单个 WorkspaceConfig 事件包含与工作区相关的配置信息，例如执行根目录。

WorkspaceStatus

单个 WorkspaceStatus 事件包含 Workspace 状态命令的结果。