BazelCon 2024 註冊現已開放！

本頁面由 Cloud Translation API 翻譯而成。

建立事件通訊協定詞彙表

7.3 · 7.2 · 7.1 · 7.0 · 6.5

每個 BEP 事件類型都有自己的語意，請盡量避免列載於 build_event_stream.proto 中。以下是各事件類型的定義。

已取消

與其他事件不同，Aborted 沒有對應的 ID 類型，因為 Aborted 事件會「取代」其他類型的事件。這個事件表示建構作業提前終止，且所顯示的事件 ID 並未正常產生。Aborted 包含列舉和容易理解的說明，用於說明建構作業未完成的原因。

舉例來說，如果使用者中斷 Bazel 時，建構作業正在評估目標，BEP 就會包含以下事件：

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

ActionExecuted

提供建構中特定動作的執行詳細資料。根據預設，這個事件只會針對失敗的動作納入 BEP，以支援找出建構失敗的根本原因。使用者可以設定 --build_event_publish_all_actions 標記，納入所有 ActionExecuted 事件。

BuildFinished

指令完成後會傳送單一 BuildFinished 事件，並包含指令的結束代碼。這個事件會提供具公信力的成功/失敗資訊。

BuildMetadata

包含 --build_metadata 旗標的剖析內容。這個事件是為了支援利用外部資料 (例如 ID) 進行 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，可協助瞭解建構工具的行為或進行偵錯。部分資訊可能會以內嵌方式列出。

{
  "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 不同)。

設定

系統會針對建構中頂層目標中使用的每個 configuration 傳送 Configuration 事件。系統一律會提供至少一個設定事件。TargetConfigured 和 TargetComplete 事件 ID 會重複使用 id，這是為了區分多重設定建構作業中的這些事件的必要元素。

{
  "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 事件。這是目標「規則種類」屬性的權威來源。套用至目標的設定會顯示在事件的已宣告 children 中。

舉例來說，使用 --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 狀態指令的結果。