建立事件通訊協定詞彙表

回報問題 查看原始碼 Nightly · 7.4 . 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

提供在建構中執行特定 Action 的詳細資料。根據預設,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 事件。系統一律會提供至少一個設定事件。TargetConfiguredTargetComplete 事件 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",
      "--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 事件 children 中的所有目標。如果模式擴展至任何 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 狀態指令的結果。